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CHAPTER 1 


Getting Around in the Networking 
services Library 


Networking is pervasive in this digital age in which we live. Information at your fingertips, 
distributed computing, name resolution, and indeed the entire Internet—the advent 

of which will be ascribed to our generation for centuries to come—imply and require | 
networking. Everything that has become the buzz of our business and personal lives, 
including e-mail, cell phones, and Web surfing, is enabled by the fact that networking 
has been brought to the masses (and we’ve barely scraped the beginning of the trend). 
You, the network-enabled Windows application developer, need to know how to lasso 
this all-important networking services capability and make it a part of your application. 
You've come to the right place. 


Networking isn’t magic, but it can seem that way to those who aren’t accustomed to 

it (or to the programmer who isn’t familiar with the technologies or doesn’t know how to 
make networking part of his or her application). That’s why the Networking Services 
Developer’s Reference Library isn’t just a collection of programmatic reference 
information; it would be only half-complete if it were. Instead, the Networking Services _ 
Library is a collection of explanatory and reference information that combine to provide 
you with the complete set that you need to create today’s network-enabled Windows 
application. | 


The Networking Services Library is the comprehensive reference guide to network- 
enabled application development. This library, like all libraries in the Windows 
Programming Reference Series (WPRS), is designed to deliver the most complete, 
authoritative, and accessible reference information available on a given subject of 
Windows network programming—without sacrificing focus. Each book in each library is 
dedicated to a logical group of technologies or development concerns; this approach has 
been taken specifically to enable you to find the information you need quickly, afficiently, 
and intuitively. — 


In addition to its networking services development information, the Networking Services 
Library contains tips designed to make your programming life easier. For example, 

a thorough explanation and detailed tour of MSDN Online is included; as is a section 
that helps you get the most out of your MSDN subscription. Just in case you don’t have 
an MSDN subscription, or don’t know why you should, I’ve included information about — 
that too, including the differences between the three levels of MSDN subscription, what 
each level offers, and why you’d want a subscription when MSDN Online i is available 
over the Internet. | 
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To ensure that you don’t get lost in all the information provided in the Networking 
Services Library, each volume’s appendixes provide an all-encompassing programming 
directory to help you easily find the particular programming element you’re looking for. 
This directory suite, which covers all the functions, structures, enumerations, and other 
programming elements found in network-enabled application development, gets you 
quickly to the volume and page you need, saving you hours of time and bucketsful 

of frustration. | 


How the Networking Services Library Is Structured 


The Networking Services Library consists of five volumes, each of which focuses on 
a particular aspect of network programming. These programming reference volumes 


_ have been divided into the following: 


e Volume 1: Winsock and QOS 

e Volume 2: Network Interfaces and Protocols 
e Volume 3: RPC and WNet ~ 

e Volume 4: Remote Access Services 

e Volume 5: Routing | 


Dividing the Networking Services Library into these categories enables you to quickly 
identify the Networking Services volume you need, based on your task, and facilitates 
your maintenance of focus for that task. This approach enables you to keep one 


reference book open and handy, or tucked under your arm while researching that aspect 


of Windows programming on sandy beaches, without risking back problems (from toting 
around all 3,000+ pages of the Networking Services Library) and without having to 
shuffle among multiple less-focused books. 


Within the Networking Services Library—and in fact, in all WPRS Libraries—each 
volume has a deliberate structure. This per-volume structure has been created to further 
focus the reference material in a developer-friendly manner, to maintain consistency 
within each volume and each Library throughout the series, and to enable you to easily 
gather the information you need. To that end, each volume in the Networking Services 
Library contains the following parts: 


e Part 1: Introduction and Overview | 
e Part 2: Guides, Examples, and Programmatic Reference 
e Part 3: Intelligently Structured Indexes 
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~ Part 1 provides an introduction to the Networking Services Library and to the WPRS 
(what you’re reading now), and a handful of chapters designed to help you get the most 
out of networking technologies, MSDN, and MSDN Online. MSDN and WPRS Libraries 
are your tools in the developer process; knowing how to use them to their fullest will 
enable you to be more efficient and effective (both of which are generally desirable 
traits). In certain volumes (where appropriate), I’ve also provided additional information| 
that you'll need in your network-enabled development efforts, and included such | 

_ information as concluding chapters in Part 1. For example, Volume 3 includes a chapter 
that explains terms used throughout the RPC development documentation; by putting 
it into Chapter 5 of that volume, you always know where to go when you have a question 
about an RPC term. Some of the other volumes in the Networking Services Library 
conclude their Part 1 with chapters that include information crucial to their volume’s 
contents, but I’ve been very selective about including such information. Publishing 
constraints have limited the amount of information | can provide in each volume 
(and in the library as a whole), so I’ve focused on the priority: getting you the most 
useful information possible within the number of pages | have to work with. 


Part 2 contains the networking reference material particular to its volume. You'll notice’ 
that each volume contains much more than simple collections of function and structure 
definitions. A comprehensive reference resource should include information about how 
to use a particular technology, as well as definitions of programming elements. 
Consequently, the information in Part 2 combines complete programming element 
definitions with instructional and explanatory material for each programming area. 


Part 3 is a collection of intelligently arranged and created indexes. One of the biggest 
challenges of the IT professional is finding information in the sea of available resources _ 
and network programming is probably one of the most complex and involved of any 
development discipline. In order to help you get a handle on network programming 
references (and Microsoft technologies in general), Part 3 puts all such information into 
an understandable, manageable directory (in the form of indexes) that enables you 

20 ee find the information you need. 


How the Networking Services Library Is Designed 


The Networking Services Library (and all libraries in the WPRS) is designed to deliver 
the most pertinent information in the most accessible way possible. The Networking _ 
Services Library is also designed to integrate seamlessly with MSDN and MSDN Online 
by providing a look and feel consistent with their electronic means of disseminating — 
Microsoft reference information. In other words, the way:a given function reference 
appears on the pages of this book has been designed specifically to emulate the way 

— that MSDN and MSDN Online present their function reference pages. 


The reason for maintaining such integration is simple: to make it easy for you to use the 
_ tools and get the ongoing information you need to create quality programs. Providing a 
“common interface” among reference resources allows your familiarity with the 
Networking Services Library reference material to be immediately applied to MSDN or 
MSDN Online, and vice-versa. In a word, it means consistency. 
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You'll find this philosophy of consistency and simplicity applied throughout WPRS 
publications. I’ve designed the series to go hand-in-hand with MSDN and MSDN Online 
resources. Such consistency lets you leverage your familiarity with electronic reference 
material, then apply that familiarity to enable you to get away from your computer if you’d 
like, take a book with you, and—in the absence of keyboards and e-mail and upright 
chairs—get your programming reading and research done. Of course, each of the 
Networking Services Library volumes fits nicely right next to your mouse pad as well, 
even when opened to a particular reference page. 


With any job, the simpler and more consistent your tools are, the more time you can 
spend doing work rather than figuring out how to use your tools. The structure and 
design of the Networking Services Library provide you with a comprehensive, 
presharpened toolset to build compelling Windows applications. 


CHAPTER 2 


What's In This Volume? 


Volume 4 of the Networking Services Developer's Reference Library gives its undivided 
attention to Remote Access Services, commonly referred to simply as RAS. 


The Remote Access Service (RAS) API is included in Microsoft Windows NT 4.0. RAS is 
used to create client applications that can display any of the Routing and RAS common 

_ dialog boxes, start and end a remote access connection, manipulate phone-book entries 
and network addresses that are mapped to phone-book entries, and get information 
about existing RAS connection status or RAS-capable devices. 


RAS makes it possible to connect a remote client computer to a network server over a 
Wide Area Network (WAN) link or a Virtual Private Network (VPN). The remote computer 
can then participate on the server’s LAN as though the remote computer was connected 
to the LAN directly. The RAS API enables programmers to access the features of RAS 
programmatically. The API is applicable in any networking environment that utilizes RAS. 
Part 2 of this volume provides a complete treatment of RAS. 


This volume also has information about how you can use development resources such 
as MSDN, MSDN Online, and developer support resources. This helpful information is 
found in various chapters in Part 1, and those chapters are common to all WPRS 
volumes. By including this information in each pan and in each volume, a aad goals of 
the WPRS are achieved: | | 


-e@ | don’t presume you have bought, or expect you to have to buy another WPRS Library 
to get access to this information. Maybe your primary focus is network programming, 
and your budget doesn’t allow for you to purchase the Active Directory Developer's 
Reference Library. Since I’ve included this information in this library, you don’t have 
to. 


e You can access this important and useful information regardless of which volume you 
have in your hand. You don’t have to (nor should you have to) fumble with another 
physical book to refer to information about how to get the most out of MSDN, or where 
to get support for questions you have about a pare: Windows development | 
problem you're having. 


e Each volume becomes more useful, more portable, and more complete in and of 
itself. This goal of the WPRS makes it easier for you to grab one of its libraries’ 
volumes and take it with you, rather than feeling like you must bring multiple volumes 
with you to have access to the library’s important overview and usability information. 


These goals have steered this library’s content and choices of included technologies; — 
| hope you find its information is useful, portable, a good value, and as accessible as it 
can be. Pe 
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Part 2 of this volume provides RAS information in the following chapter-based focuses: 


RAS Programming Guide 


This guide takes you through the steps necessary to implement RAS capabilities in your 
Windows application. All such tasks are grouped in task-oriented categories, such as 
connection operations, AutoDial, server administration, and more. 


RAS Reference © 


A collection of chapters appears after the RAS programming guide that provide a 
complete treatment of the RAS API. 


RRAS Overview 


This chapter provides an overview of the new Remote Access capabilities built into 
RRAS, which is the successor of RAS. 


RAS Administration 


This chapter provides information and programmatic reference for performing RAS 


| Administration programming using RRAS-based RAS administration. Where there are 


differences in the treatment of RAS on Windows NT 4.0 and Windows 2000, such 
differences are clearly ne in the text. 


EAP 


Windows 2000 supports the Extensible Authentication Protocol (EAP). EAP allows third- 
party authentication modules to interact with the implementation of the Point-to-Point 
Protocol (PPP) included in Windows 2000 Remote Access Service (RAS). _ 


EAP is an extension to PPP, providing a standard support mechanism for authentication 
schemes such as token cards, Kerberos, Public Key, and S/Key. EAP has been made 
available in response to increasing demand to augment RAS authentication with third- 
party security devices. . 


EAP is fully supported on both the Windows 2000 Dial-Up Server and the Dial- Up 
Networking Client. EAP is a critical technology component for secure Virtual Private 


- Networks (VPN), protecting them against “brute force” or “dictionary” attacks and | 


password guessing. 


EAP | improves on previous authentication protocols such as Password Authentication 
Protocol (PAP) and Challenge Handshake Authentication Protocol (CHAP). Windows 


2000 supports these earlier authentication protocols as well. 


Tracing 


The final chapter i in this volume describes the implementation of the common tracing 
DLL, which provides a uniform mechanism for generating diagnostic output for the 
Windows NT/Windows 2000 Routing and RAS components (as well as any other 
application that wishes to use the DLL). The DLL provides dynamic configuration 
change, allowing a user to direct output to a console or to a specified file. | 


CHAPTER 3 


Using Microsoft Reference 
Resources 


Keeping current with all the latest information on the latest networking technology is like 
trying to count the packets going through routers at the MAE-WEST Internet service 
exchange by watching their blinking activity lights: It’s impossible. Often times, 
application developers feel like those routers might feel at a given day’s peak activity; too 
much information is passing through them, none of which is being absorbed or passed 
along fast enough for their boss’ liking. | 


For developers, sifting through all the available information to get to the required 

_ information is often a major undertaking, and can impose a significant amount of 

~ overhead upon a given project. What’s needed is either a collection of information that 
has been sifted for you, shaking out the information you need the most and putting that 
pertinent information into a format that’s useful and efficient, or direction on how to sift 
the information yourself. The Networking Services Developer's Reference Library does | 
the former, and this chapter and the next provide you with the latter. | 


This veritable white noise of information hasn’t always been a problem for network 
programmers. Not long ago, getting the information you needed was a challenge 
because there wasn’t enough of it; you had to find out where such information might be 
located and then actually get access to that location, because it wasn’t at your fingertips - 
or on some globally available backbone, and such searching took time. In short, the 
availability of information was limited. | 


Today, the volume of information that surrounds us sometimes numbs us; we’re 
overloaded with too much information, and if we don’t take measures to filter out what 

_ we don’t need to meet our goals, soon we become inundated and unable to discern — 

~ what’s “white noise” and what’s information that we need to stay on top of our respective 
fields. In short, the overload of available information makes it more difficult for us to find 
what we really need, and wading through the deluge slows us down. | 


This fact applies equally to Microsoft's reference material, because there is so 5 much: 
information that finding what you need can be as challenging as figuring out what to do 
with it once you have it. Developers need a way to cut through what isn’t pertinent to. 
them and to get what they’re looking for. One way to ensure you can get to the | 
information you need is to understand the tools you use; carpenters know how to use 
nail-guns, and it makes them more efficient. Bankers know how to use ten-keys, and it — 
makes them more adept. If you’re a developer of Windows applications, two tools you - 
should know are MSDN and MSDN Online. The third tool for developers—reference 
books from the WPRS—can help you get the most out of the first two. 
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Books in the WPRS, such as those found in the Networking Services Developer's 
Reference Library, provide reference material that focuses on a given area of Windows 
programming. MSDN and MSDN Online, in comparison, contain all of the reference 
material that all Microsoft programming technologies have amassed over the past few 
years, and create one large repository of information. Regardless of how well such 
information is organized, there’s a lot of it, and if you don’t know your way around, 
finding what you need (even though it’s in there, somewhere) can be frustrating, time- 
consuming, and just an overall bad experience. | 


This chapter will give you the insight and tips you need to navigate MSDN and MSDN 
Online and enable you to use each of them to the fullest of their capabilities. Also, other 
Microsoft reference resources are investigated, and by the end of the chapter, you'll 
know where to go for the Microsoft reference information you need (and how to quickly 
and efficiently get there). 


The Microsoft Developer Network 


MSDN stands for Microsoft Developer Network, and its intent is to provide developers 
with a network of information to enable the development of Windows applications. Many 
people have either worked with MSDN or have heard of it, and quite a few have one of 
the three available subscription levels to MSDN, but there are many, many more who 
don’t have subscriptions and could use some concise direction on what MSDN can do — 
for a developer or development group. If you fall into any of these categories, this 
section is for you. 


There is some clarification to be done with MSDN and its offerings; if you've heard of 
MSDN, or have had experience with MSDN Online, you may have asked yourself one of 
these questions during the process of getting up to speed with either resource: 


e Why do | need a subscription to MSDN if resources such as MSDN Online are 
accessible for free over the Internet? 


_@ What is the difference between the three levels of MSDN subscriptions? 


e is there a difference between MSDN and MSDN Online, other than the fact that one is 
on the Internet and the other i is on a CD? Do their features overlap, separate, 
coincide, or what? 


If you have asked any of these questions, then lurking somewhere in the back of your 
thoughts has probably been a sneaking suspicion that maybe you aren’t getting the most 
out of MSDN. Maybe you’re wondering whether you’re paying too much for too little, or 
not enough to get the resources you need. Regardless, you want to be in the know and 
not in the dark. By the end of this chapter, you'll know the answers to all these questions 
and more, along with some effective tips and hints on how to make the most effective 
use of moon and MSDN Online. 7 
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Comparing MSDN with MSDN Online 


Part of the challenge of differentiating between MSDN and MSDN Online comes with 
determining which has the features you need. Confounding this differentiation is the fact 
that both have some content in common, yet each offers content unavailable with the 
other. But can their difference be boiled down? Yes, if broad strokes and some 
generalities are used: 


° MSDN provides reference content and the latest Microsoft product software, all 
shipped to its subscribers on CD or DVD. 


e MSDN Online provides reference content and a development community forum, and 
is available only over the Internet. 


Each delivery mechanism for the content that Microsoft is making available to Windows 
developers is appropriate for the medium, and each plays on the strength of the medium 
to provide its “customers” with the best possible presentation of material. These 
strengths and medium considerations enable MSDN and MSDN Online to provide 
developers with different feature sets, each of which has its advantages. 


MSDN is perhaps less “immediate” than MSDN Online because it gets to its subscribers 
in the form of CDs or DVDs that come in the mail. However, MSDN can sit in your 
CD/DVD drive (or on your hard drive), and isn’t subject to Internet speeds or failures. 
Also, MSDN has a software download feature that enables subscribers to automatically 
update their local MSDN content over the Internet, as soon as it becomes available, 
without having to wait for the update CD/DVD to come in the mail. The interface with 
which MSDN displays its material—which looks a whole lot like a specialized browser 
window—is also linked to the Internet as a browser-like window. To further coordinate 
MSDN with the immediacy of the Internet, MSDN Online has a section of the site 
dedicated to MSDN subscribers that enable subscription material to be updated (on their 
local machines) as soon as it’s available. | 


MSDN Online has lots of editorial and technical columns that are published directly to 
the site, and are tailored (not surprisingly) to the issues and challenges faced by 
developers of Windows applications or Windows-based Web sites. MSDN Online also 
has a customizable interface (somewhat similar to MSN.com) that enables visitors to 
tailor the information that’s presented upon visiting the site to the areas of Windows 
development in which they are most interested. However, MSDN Online, while full of 
up-to-date reference material and extensive online developer community content, 
doesn’t come with Microsoft product software, and doesn’t reside on your local machine. 


Because it’s easy to confuse the differences and similarities between MSDN and MSDN 
Online, it makes sense to figure out a way to quickly identify how and where they depart. 
Figure 3-1 puts the differences—and similarities—between MSDN and MSDN Online 
into a quickly identifiable format. 
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Remember, too, that if you are an MSDN subscriber, you can still use MSDN Online and 
its features. So it isn’t an “either/or” question with regard to whether you need an MSDN 
subscription or whether you should use MSDN Online; if you have an MSDN 
subscription, you will probably continue to use MSDN Online and the additional features 
provided with your MSDN subscription. 


MSDN Subscriptions 


If you’re wondering whether you might benefit from a subscription to MSDN, but you 
aren’t quite sure what the differences between its subscription levels are, you aren't 
alone. This section aims to provide a quick guide to the differences in subscription levels, 
and even provides an estimate for what each subscription level costs. 


The three subscription levels for MSDN are: Library, Professional, and Universal. Each 
has a different set of features. Each progressive level encompasses the lower level’s 
features, and includes additional features. In other words, with the Professional 
subscription, you get everything provided in the Library subscription plus additional 
features; with the Universal subscription, you get everything provided in the nfolessional 
subscription plus even more features. 


MSDN Library Subscription 


The MSDN Library subscription is the basic MSDN subscription. While the Library 
subscription doesn’t come with the Microsoft product software that the Professional and 
Universal subscriptions provide, it does come with other features that developers may 

_ find necessary in their development effort. With the Library subscription, you get the 
following: 


e The Microsoft reference library, including SDK and DDK documentation, updated 
quarterly 

-@ Lots of sample code, which you can cut-and-paste into your projects, royalty free 

e The complete Microsoft Knowledge Base—the collection of bugs and workarounds 

e Technology specifications for Microsoft technologies 


e The complete set of product documentation, such as Microsoft Visual Studio, 
Microsoft Office, and others 


e Complete (and in some cases, partial) electronic copies of selected books and: 
magazines | | 


e Conference and seminar papers—if you weren't there you can use MSDN’ S notes 


In addition to these items, you also get: 


e Archives of MSDN Online columns 
_. @ Periodic e-mails from Microsoft chock full of development-related information 
~e A subscription to MSDN News, a bi-monthly newspaper from the MSDN folks 
© Access to subscriber-exclusive areas and material on MSDN Online 
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MSDN Professional Subscription 


The MSDN Professional subscription is a superset of the Library subscription. In addition 
to the features outlined in the previous section, MSDN Professional subscribers get the 
following: 


¢ Complete set of Windows operating systems, including release versions of 
Windows 95, Windows 98, and Windows NT 4 Server and Workstation 

e Windows SDKs and DDKs in their entirety 

e International versions of Windows operating systems (as ceeens 

e Priority technical support for two incidents in a development and test environment 


MSDN Universal Subscription 


The MSDN Universal subscription is the all-encompassing version of the MSDN 
subscription. In addition to everything provided in the Professional subscription, 
Universal subscribers get the following: 


e The latest version of Visual Studio, Enterprise Edition 


e The Microsoft BackOffice test platform, which includes all sorts of Microsoft product — 
software incorporated in the BackOffice family, each with a special 10-connection 
license for use in the development of your software products 


e Additional development tools, such as Office Developer, Microsoft Eonthage: and 
Microsoft Project 


e Priority technical support for two additional incidents in a development and test 
environment (for a total of four incidents) 


Purchasing an MSDN Subscription 


Of course, all the features that you get with MSDN subscriptions aren’t free. MSDN 
subscriptions are one-year subscriptions, which are current as of this writing. Just as 
each MSDN subscription escalates in functionality of incorporation of features, so does 
each escalate in price. Please note that prices are subject to change. | 


The MSDN Library subscription has a retail price of $199, but if you’re renewing an 
existing subscription you get a $100 rebate in the box. There are other perks for existing 


Microsoft customers, but those vary. Check out the Web site for more details. 


The MSDN Professional subscription is a bit more expensive than the Library, witha 
retail price of $699. If you’re an existing customer renewing your subscription, you again 
get a break in the box, this time in the amount of a $200 rebate. You also get that break 
if you’re an existing Library subscriber who’s upgrading to a Professional subscription. 


The MSDN Universal subscription takes a big jump in price, sitting at $2,499. If you’re 
upgrading from the Professional subscription, the price drops to $1,999, and if you’re 
upgrading from the Library subscription level, there’s an in-the-box rebate for $200. 
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As is often the case, there are academic and volume discounts available from various 
resellers, including Microsoft, so those who are in school or in the corporate environment 
can use their status (as learner or learned) to get a better dealt-—and in most cases, the 
deal is in fact much better. Also, if your organization is using lots of Microsoft products, 
whether or not MSDN is a part of that group, ask your purchasing department to look into 
the Microsoft Open License program; the Open License program gives purchasing 
breaks for customers who buy lots of products. Check out www.microsoft.com/licensing 
for more details. Who knows, if your organization qualifies you could end up getting an 
engraved pen from your purchasing department, or if you’re really lucky maybe even a 
plaque of some sort for saving your company thousands of dollars on Microsoft products. 


You can get MSDN subscriptions from a number of sources, including online sites 
specializing in computer-related information, such as www.iseminger.com (shameless 
self-promotion, | know), or from your favorite online software site. Note that not all 
software resellers carry MSDN subscriptions; you might have to hunt around to find one. 
Of course, if you have a local software reseller that you frequent, you can check out 
whether they carry MSDN subscriptions. 


_ As an added bonus for owners of this Networking Services Developer’s Reference 
Library, in the back of Volume 1, you'll find a $200 rebate good toward the purchase of 
an MSDN Universal subscription. For those of you doing the math, that means you 
actually make money when you purchase the Networking Services Developer's 
Reference Library and an MSDN Universal subscription. With this rebate, every 
developer in your organization can have the Networking Services Developer's Refence - 
Library on their desk and the MSDN Universal subscription on thier desktop, and still 
come out $50 ahead. That’s the kind of math even accountants can like. 


Using MSDN 


MSDN subscriptions come with an installable interface, and the Professional and 
Universal subscriptions also come with a bunch of Microsoft product software such as 
_ Windows platform versions and BackOffice applications. There’s no need to tell you how 
_ to use Microsoft product software, but there’s a lot to be said for providing some quick 
but useful guidance on getting the most out of the interface to present and navigate 
_ through the seemingly endless supply of reference material provided with any MSDN 
subscription. 


To those who have used MSDN, the interface shown in Figure 3-2 Is likely familiar: it’s 
the navigational front-end to MSDN reference material. 


The interface is familiar and straightforward enough, but if you don’t have a grasp on its 
features and navigation tools, you can be left a little lost in its sea of information. With a 
few sentences of explanation and some tips for effective navigation, however, you can 

increase its effectiveness dramatically. 
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Navigating MSDN 


One of the primary features of MSDN—and to many, its primary paraweenie2 the cheer 
volume of information it contains, over 1.1GB and growing. The creators of MSDN likely 
realized this, though, and have taken steps to assuage the problem. Most of those steps 
relate to enabling developers to selectively navigate through MSDN’s content. 


E? MSDN Library - October 1999 


Entire Collection] 
MSDN Library - 
October 1999 


oe : Welcome to the MSDN Library 
- Visual Studio 6.0 Documentation Welcome to the October 1999 


@- Office Developer Documentation release of the MSDN Library. 

@& Windows CE Documentation . | 

@ Platform SDK The MSDN Library is the essential reference for developers, with 
@ SDK Documentation more than a gigabyte of technical programming information, 

@ DDK Documentation including sample code, documentation, technical articles, the 


Hi @® Windows Resource Kits Microsoft Developer Knowledge Base, and anything else you 


@ Tools and Technologies 
@ Knowledge Base 
@ Technical Articles 
@ Backgrounders 
@: Specifications 

ae Books Dr. GUI's Espresso Stand 
tb Partial Books 

& 


might need to develop solutions that implement Microsoft 
technology. 


a] Periodicals Dr. GUI introduces the Octaber 1999 release of the MSDN Library. The 
a good doctor examines new Library content, including articles and 
documentation about Windows 2000, Windows CE, Office 2000, and 
databases and data access, plus several new technical article sample 
suites. 


Samples 


Read through this HcerABHE fcr summaries of what's new and follow 
the links to the new titles, 


Figure 3-2: The MSDN interface. 


Basic navigation through MSDN is simple and is a lot like navigating through Microsoft 


Windows Explorer and its folder structure. Instead of folders, MSDN has books into 
which it organizes its topics; expand a book by clicking the + box to its left, and its 
contents are displayed with its nested books or reference pages, as shown in Figure 3-3. 
lf you don't see the left pane in your MSDN viewer, go to the wiew menu and select 
Navigation Tabs and they’ l appear. 


The four tabs in the left pane of MSDN— increasingly referred to as property sheets 
these days—are the primary means of navigating through MSDN content. These four 
tabs, in coordination with the Active Subset drop-down box above the four tabs, are the 
tools you use to search through MSDN content. When used to their full extent, these 
coordinated navigation tools greatly improve your MSDN experience. 
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{Entire Collection) 


MADCAP 


DN Li rary - ctober 1999 
& @ Welcome to the MSDN Library 
es a Visual Studio 6.0 Documentation Purpose General 


S oii information 
es Office Developer Documentation MADCAP, or Multicast Address inform 
fe @ Windows CE Documentation D ic Client All ti about 
(6) Platform SDK See meee os * MADCAP, 
& Protocol, is a technology 
 @ Getting Started 


é aimed at making it easy for . 
& Desion atetesen ond Siaeers clients to renew and release Reference 
@ Base Services 


Multicast addresses, enablin 
f= @ Component Services rea 3 Documentation 
clients to dynamically of MADCAP 
i) e Data Access Services A u Ha i : 
connect" and "disconnect functions and 
2) @ Graphics and Multimedia Services fonimoticac: wotwork 
— @ Management Services structures. 


& Messaging and Collaboration Services eee 

1 Q3) Networking and Directory Services The development of feedback 
& @ Active Directory, ADSI, and Directory Services standards for MADCAP is 
‘ @ Common Intemet File System Protocol ongoing, and falls under the 
i @ Fax Service . Multicast Address Allocation 
4) @ Intemet Protocol Helper (malloc) Working Group at the requests 
Fl x ee Lightweight Directory Access Protocol (LDAP) A IETF. diractly to 
& @ Microsoft SNA Server . Microsoft. 

prance Chent Allocation Prat Where Applicable 


Developers can use MADCAP 
to: 


Overview 


Make error 
reports and 
feature 


Figure 3-3: Basic navigation through MSDN. 


The Active Subset drop-down box is a filter mechanism; choose the subset of MSDN 
_information you’re interested in working with from the drop-down box, andthe 
information in each of the four Navigation Tabs (including the Contents tab) limits the 
information it displays to the information contained in the selected subset. This means 
that any searches you do in the Search tab, and in the index presented in the Index tab, 
are filtered by their results and/or matches to the subset you define, greatly narrowing 
the number of potential results for a given inquiry. This enables you to better find the 
information you're really looking for. In the Index tab, results that might match your 
inquiry but aren’t in the subset you have chosen are grayed out (but still selectable). In 
the Search tab, they simply aren't displayed. 


MSDN comes with the following predefined subsets (these subsets are subject to 
change, based on documentation updates and TOC reorganizations): 


Entire Collection | Platform SDK, Networking Services. 


MSDN, Books and Periodicals Platform SDK, Security | 
MSDN, Content on Disk 2 only _ Platform SDK, Tools and Languages — 
~ (CD only — not in DVD version) Platform SDK, User Interface Services 
MSDN, Content on Disk3 only Platform SDK, Web Services | 
_ (CD only — not in DVD version) _ Platform SDK, Win32 API - 
MSDN, Knowledge Base Repository 2.0 Documentation 
MSDN, Technical Articles and Pe ane Visual Basic Documentation 


Backgrounders —  Migual C++ Documentation 
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Office Developer Documentation Visual C++, Platform SDK and 


Platform SDK, BackOffice ~ WinCE Docs 

Platform SDK, Base Services . Visual C++, Platform SDK, and 

Platform SDK, Component Services Enterprise Docs 

Platform SDK, Data Access Services Visual FoxPro Documentation 

Platform SDK, Getting Started Visual InterDev Documentation 

Platform SDK, Graphics and | Visual J++ Documentation 
Multimedia Services Visual SourceSafe Documentation 

Platform SDK, Management Services Visual Studio Product Documentation 

Platform SDK, Messaging and Windows CE Documentation 


Collaboration Services 


As you can see, these filtering options essentially mirror the structure of information 
delivery used by MSDN. But what if you are interested in viewing the information in a 
handful of these subsets? For example, what if you want to search on a certain keyword 
through the Platform SDK’s ADSI, Networking Services, and Management Services 
subsets, as well as a little section that’s nested way into the Base Services subset? 
Simple—you define your own subset by choosing the View menu, and then selecting the 
Define Subsets menu item. You’re presented with the window shown in Figure 3-4. 


Defining a subset is easy; just take the following steps: 


1. Choose the information you want in the new subset; you can choose entire subsets or 
selected books/content within available subsets. 


_ 2. Add your selected information to the subset you’re creating by clicking the Add button. 


3. Name the newly created subset by typing in a name in the Save New Subset As box. 
Note that defined subsets (including any you create) are arranged in alphabetical 
order. 


You can also delete entire subsets from the MSDN installation. Simply select the subset 
you want to delete from the Select Subset To Display drop-down box, and then click the 
nearby Delete button. 


Once you have defined a subset, it becomes available in MSDN just like the predefined 
subsets, and filters the information available in the four Navigation Tabs, just like the 
predefined subsets do. | 


Quick Tips 


Now that you know how to navigate MSDN, there are a handful of tips and tricks that you 
can use to make MSDN as effective as it can be. 


Use the Locate button to get your bearings. Perhaps it’s human nature to need to 
know where you are in the grand scheme of things, but regardless, it can be bothersome 
to have a reference page displayed in the right pane (perhaps jumped to from a search), 
without the Contents tab in the left pane being synchronized in terms of the reference 
page’s location in the information tree. Even if you know the general technology in which 
your reference page resides, it’s nice to find out where it is in the content structure. 
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This is easy to fix. Simply click the Locate button in the navigation toolbar and all will be 
synchronized. 
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Figure 3-4: The Define Subsets window. 


Use the Back button just like a browser. The Back button in the navigation toolbar 
functions just like a browser’s Back button; if you need information on a reference page 
you viewed previously, you can use the Back button to get there, rather than going 
through the process of doing another search. 


Define your own subsets, and use them. Like | said at the beginning of this chapter, 
the volume of information available these days can sometimes make it difficult to get our 
work done. By defining subsets of MSDN that are tailored to the work you do, you can 
become more efficient. 


Use an underscore at the beginning of your named subsets. Subsets in the Active 
Subset drop-down box are arranged in alphabetical order, and the drop-down box shows 
only a few subsets at a time (making it difficult to get a grip on available subsets, | think). 
Underscores come before letters in alphabetical order, so if you use an underscore on all 
of your defined subsets, you get them placed at the front of the Active Subset listing of 
available subsets. Also, by using an underscore, you can immediately see which subsets 
you’ve defined, and which ones come with MSDN—it saves a few seconds at most, but 
those seconds can add up. 
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Using MSDN Online 


MSDN underwent.a redesign in December of 1999, aimed at streamlining the 
information provided, jazzing things up with more color, highlighting hot new 


technologies, and various other improvements. Despite its visual overhaul, MSDN Online 


still shares a lot of content and information delivery similarities with MSDN, and those 
similarities are by design; when you can go from one developer resource to another and 
immediately work with its content, your job is made easier. However, MSDN Online is 
different enough that it merits explaining in its own right—it’s a different delivery medium, 
and can take advantage of the Internet i in ways that MSDN simply cannot. 


If you’ve used MSN’s home page before (www.msn.com), you’re familiar with the fact 
that you can customize the page to your liking; choose from an assortment of available 
national news, computer news, local news, local weather, stock quotes, and other | | 
collections of information or news that suit your tastes or interests. You can even insert a 
few Web links and have them readily accessible when you visit the site. The MSDN 
Online home page can be customized in a similar way, but its collection of headlines, 
information, and news sources are all about development. The information you choose 
specifies the information you see when you go to the MSDN Online home page, just like 
the MSN home page. 


There are a couple of ways to ait to the customization page; you can go to the MSDN 
Online home page (msdn.microsoft.com) and click the Personalize This Site button near 
the top of the page, or you can go there directly by pointing your browser to 
msdn.microsoft.com/msdn- online/start/custom. However you get there, the page you'll 
see is shown in Figure 3-5. 


As you can see from Figure 3-5, there are lots of technologies to eaoee from (many 
more options can be found when you scroll down through available technologies). If 
you're interested in Web development, you can select the checkbox at the left of the 
page next to Standard Web Development, and a predefined subset of Web-centered 
technologies is selected. For technologies centered more on Network Services, you can 
go through and choose the appropriate technologies. If you want to choose all the 
technologies in a given technology group more quickly, click the Select All button in the 
technology’s shaded title area. | 


You can also choose which tab is sblected by default in the home page that MSDN ~ 
Online presents to you, which is convenient for dropping you into the category of MSDN 
Online information that interests you most. All five of the tabs available on MSDN 


_Online’s home page are available for selection; those tabs are the following: 


e Features 

e News 

e Columns 

e Technical Articles 
¢ Training & Events 
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Personalize your Start page - Microsoft Interne 


All Produ Support | arch | rovers 


Preset Templates 


Select or clear the check boxes 


below ta choose a pre-set — Personalize the information that appears on your MSDN Online home page. 


template of information for that 
technology Select your preferences from the sections below, then return here and choose Save, (Yes, we 


know it's a lot of choices. There's a lot of information on this site.) You can update your choices 


[j Database at any time by visiting this Personalization page. 


Development/Administration 


Database Web Development 


Training & Events | My Links 


Office/‘VB4 Developer 


Standard Web Development sons 
[ ActiveX Controls 


Component Object Model orl COM+ (Component Services) 
. DCOM ae : Design-Time Controls 
Message Queuing (MSMQ) Microsoft Transaction Server (MTS) 


| Server components 


Windows Development 


Databases (General Info) ADO 
DAO. | ay, | Data Binding 


: Data transformation 


Figure 3-5: The MSDN Online Personalize Page. 


Once you’ve defined your profile—that is, customized the MSDN Online content you 
want to see—MSDN Online shows you the most recent information pertinent to your 
profile when you go to MSDN Online’s home page, with the default tab you ve chosen 
displayed upon loading of the MSDN Online home page. 


Finally, if you want your profile to be available to you regardless of which computer 
you're using, you can direct MSDN Online to store your profile. Storing a profile for _ 
MSDN Online results in your profile being stored on MSDN Online’s server, much like 
roaming profiles in Windows 2000, and thereby makes your profile available to you 
regardless of the computer you’re using. The option of storing your profile is available 
when you customize your MSDN Online home page (and can be done any time 
thereafter). The storing of a profile, however, requires that you become a registered 
member of MSDN Online. More information about becoming a registered MSDN Online 
user is provided in the section titled MSDN Online Registered Users. 
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Navigating MSDN Online 


Once you’re done customizing the MSDN Online home page to get the information 

you’re most interested in, navigating through MSDN Online is easy. A banner that sits 

just below the MSDN Online logo functions as a navigation bar, with drop-down menus 
_ that can take you to the available areas on MSDN Online, as Figure 3-6 illustrates. 


My Lae 
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Windows 2000 
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& Partnering new version of the parser is better equipped for server 
International use. (Dee Zi, Colurand . 
My Links 


* IT Professionals 


Ad varced: 


Visual Studio 


DLL Help 
Database 


ff MSDN dcunsedption 


| MSDN Flash 
te newsletter) 


6 Send Us 
Your Feedback 


(ga) Site Guide 


Tune in to the MSDN Show 
Learn about new technologies coming out of Microsoft in MSDN Online’ 5 


first streaming media show. This show's topics include XML and BizTalk. 


Dec 15, Stream 


rey iden | 


introducing the New MSDN Online 
MSDN Online managing editor Norvin Leach exolains the new desian. of 


Figure 3-6: The MSDN Online Navigation Bar with Its Drop-Down Menus. 


Following is a list of available menu eatogones: which Cs the available sites and 
features within MSDN Online: 


Home | Resources 
Magazines | Downloads 
Libraries | Search MSDN 


Developer Centers 


The navigation bar is available regardless of where you are in MSDN Online, so the 
capability to navigate the site from this familiar menu is always available, leaving you a 
click away from any area on MSDN Online. These menu categories create a functional 
and logical grouping of MSDN Online’s feature offerings. 
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MSDN Online Features 


Each of MSDN Online’s seven feature categories contains various sites that comprise 
the features available to developers visiting MSDN Online. 


Home is already familiar; clicking on Home in the navigation bar takes you to the MSDN 
Online home page that you’ve (perhaps) customized, showing you all the latest 
information about technologies that you’ve indicated you’re interested in reading about. 


Magazines is a collection of columns and articles that comprise MSDN Online’s 
magazine section, as well as online versions of Microsoft’s magazines such as MSu, 
MIND, and the MSDN Show (a Webcast feature introduced with the December 1999 
remodeling of MSDN Online). The Magazines feature of MSDN Online can be linked to 
directly at msdn.microsoft.com/resources/magazines.asp. The Magazines home page is 
shown in Figure 3-7. | 


soe * Magazines 


MIND « Print and online publications for current information on all types of development. 


MSON Newspaper « 
MSON Show « 


Micrasaft Systems Journal (MS3} 


§4S7 is the magazine that brings developers monthly features on the most important tools and . 
technologies such as ML, Windows 2000, ATL, MFC, Windows CE, DirectX, C++, as well as monthly 
columns on visual programming, Win 32, COM, debugging, security, and more. 


“Microsoft Internet Developer (MIND) 


MIND is the monthly magazine for Internet and intranet developers that covers tools and technologies 
including XML, Visual Basic, scripting, 4D0, SQL Server, IIS, and anything else a developer might need 
to build an interactive or e-commerce site. 


MSDN News 


The MSON News is a printed newspaper, published bi-monthly for the developer audience. The 
newspaper features new technical articles and ongoing columns, including the popular "Ask Dr, GUI," as 
well as a regular series of posters. Subscriptions are free to MSDN subscribers. 


The MSDN Show 


This regular Webcast brings you inside Microsoft to talk with developers and planners about our hottest - 
new technologies, The segments range from broad overviews to down-and-dirty coding, with some 
news and entertainment mixed in, too, 


Figure 3-7: The Magazines Home Page. 


For those of you familiar with the Voices feature section that formerly found its home on 
the MSDN Online navigation banner, don’t worry; all content formerly in the Voices 
section is included the Magazines section as a subsite (or menu item, if you prefer) of 
the Magazines site. For those of you who aren’t familiar with the Voices subsite, you'll 
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find a bunch of different articles or “voices” there, each of which adds its own particular 
twist on the issues that face developers. Both application and Web developers can get 
their fill of magazine-like articles from the sizable list of different articles available (and 
frequently refreshed) in the Voices subsite. With the combination of columns and online 
developer magazines offered in the ogee section, you’re sure to find plenty of 
interesting insights. 


Libraries is where the reference material available on MSDN Online lives. The Libraries 
site is divided into two sections: Library and Web Workshop. This distinction divides the 
reference material between Windows application development and Web development. 
Choosing Library from the Libraries menu takes you to a page through which you can 
navigate in traditional MSDN fashion, and gain access to traditional MSDN reference 
material. The Library home.page can be linked to directly at msdn.microsoft.com/library. 
Choosing Web Workshop takes you to a site that enables you to navigate the Web 


‘Workshop in a slightly different way, starting with a bulleted list of start points, as shown 


in Figure 3-8. The Web Workshop home page can be linked to directly at 
msdn.microsoft.com/workshop. 
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Figure 3-8: The Web Workshop Home Page. 
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Developer Centers is a hub from which developers who are interested in a particular 
area of development—such as Windows 2000, SQL Server, or XML—can go to find 
focused Web site centers within MSDN Online. Each developer center is dedicated to 
providing all sorts of information associated with its area of focus. For example, the 
Windows 2000 developer center has information about what’s new with Windows 2000, 
including newsgroups, specifications, chats, knowledge base articles, and news, among 
others. At publication time, MSDN Online had the following developer centers: 


e Microsoft Windows 2000_ 

e Microsoft Exchange 

e Microsoft SQL Server 

e Microsoft Windows Media 

° XML | | ; 

In addition to these developer centers is a promise that new centers would be added to 
the site in the future. To get to the Developer Centers home page directly, link to 


msdn.microsoft.com/resources/devcenters.asp. Figure 3-9 shows the Developer Centers 
home page. | | 


MSDN Developer 


Besa 


ES http: #/msdn. microsoft. com/resources/devcenters. asp 


OOO % RP 


All Products | Support | arch | rmoicr 


Microsoft windows * MSDN Developer Centers 


Microsoft Exchange MSDN Developer Centers provide access to all the developer resources MSDN has to offer for specific 
‘Microsoft SOL Server products and technologies. From the Developer Centers you can also find the latest links to all the best 


WisiosoR Windows new technical articles, downloads, samples, product news, and more. While we'll be adding more 


Media Developer Centers to the site in the future, you can visit the following Developer Centers today: 
MML oe | ' : 


soft Windows 2O00 
Micrasoft Exchange 
‘Microsoft SQL Server 
Microsoft Windows Media 
ML 


Figure 3-9: The Developer Centers Home Page. 
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Resources is a place where developers can go to take advantage of the online forum of 
Windows and Web developers, in which ideas or techniques can be shared, advice can 
be found or given (through MHM, or Members Helping Members), and the MSDN User 
Group Program can be joined or perused to find a forum to voice their opinions or chat 
with other developers. The Resources site is full of all sorts of useful stuff, including 
featured books, a DLL help database, online chats, case studies, and more. The 
Resources home page can be linked to directly at msdn.microsoft.com/resources. Figure 
3-10 provides a look at the Resources home page. 


MSDN Online Resources - Microsoft Internet Explorer 


} http: 4/msdn.microsoft.com/resources/ 


DLL Help Database 
MSON Online Support 


Additional MSDN Online Resources 


laciecroune MSDN Online is about more than just technical articles and documentation. Check out the wide variety 


Peer Journal 


Members Helping 
Mernbers 


MISOM User Group 
Program 


MSBN Online Chats 
MSCM Training 


of resources we offer to help you get your jab done. 


The DLL Help Database 


Microsoft's DLL Help database provides a searchable database of information about file versions that 
ship with a selected set of Microsoft products, 


MSDN Online Support 


Events MSDN Online Support offers a large variety of technical resources, including the Microsoft Knowledge 


Base; service packs, hotfixes, and taols; and Support Web Casts, live presentations by Support 
professionals. 


Developer Books 


Newsgroups 


MSDN Online provides access to selected developer-focused public newsgroups through our browser- 
based newsreader, Microsoft's public newsgroups allaw you to interact with the Microsoft developer 
community and MYPs (Mast Valuable Professionals). Public newsgroups are a great way to solve 
technical problems, learn more about a specific product or technology, or keep up with the latest buzz 
in the developer cornmunity. Microsoft employees da not monitor Microsoft's public newsgroups. 


Peer Journal 


Microsoft's collection of code, tips, and articles written by your developer peers. 


Figure 3-10: The Resources Home Page. 


The Downloads site is where developers can find all sorts of useable items fit to be 
downloaded, such as tools, samples, images, and sounds. The Downloads site is also 
where MSDN subscribers go to get their subscription content updated over the Internet 
to the latest and greatest releases, as described previously in this chapter in the i 
MSDN section. The Downloads home page can be linked to directly at 
msdn.microsoft.com/downloads. The Downloads home page is shown in Figure fe 11. 
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Tools 
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end-to-end application architecture and design. 
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Figure 3-11: The Downloads Home Page. 


The Search MSDN site on MSDN Online has been improved over previous versions, 
and includes the capability to restrict searches to either library (Library or Web 
Workshop), as well as other fine-tune search capabilities. The Search MSDN home page 
can be linked to directly at msdn.microsoft.com/search. The Search MSDN home page is 
shown in Figure 3-12. 


There are two other destinations within MSDN Online of specific interest, neither of 
which is immediately reachable through the MSDN navigation bar. The first is the MSDN 
Online Member Community home page, and the other is the Site Guide. 
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€| http: //search. microsoft. com/us/dev/default. asp 


rmiicras ott 


Choosing this option will allow you to search the developer topics in the Microsoft Knowledge 
Or you can go to the Support area for an advanced Knowledge Base Search. 


Figure 3-12: The Search MSDN Home Page. 


The MSDN Online Member Community home page can be directly reached at 
msdn.microsoft.com/community. Many of the features found in the Resources 
navigation menu are actually subsites of the Community page. Of course, becoming a 
member of the MSDN Online member community requires that you register (See the next 
section for more details on joining), but doing so enables you to get access to Online 
Special Interest Groups (OSIGs) and other features reserved for registered members. 
The Community page is shown in Figure 3-13. | 


Another destination of interest on MSDN Online that isn’t displayed on the navigation 
banner is the Site Guide. The Site Guide is just what its name suggests—a guide to the 
MSDN Online site that aims at helping developers find items of interest, and includes 
links to other pages on MSDN Online such as a recently posted files listing, site maps, 
glossaries, and other useful links. The Site Guide home page can be linked to directly at 
msdn.microsoft.cor/siteguide. : ee 
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(>MSDWN Online Community Home - Microsoft Internet Explorer Ss 


Welcome to the MSDN Online Member Community 
Updated October 14, 1999 


Join « 
‘Your Mambership « . : 

sige « With an MSDN Online membership, developers can easily access technical 
information, tools, and a community of developers ready to help solve the 
toughest challenges, icin new and take advantage of member benefits. 


Peer Journal ¢ 


Case Studies « 


Downloads : : 
Online Special-Interest Groups 
Members Helping « 


i Mernbers Access the information you need, when you need it, with Ordine Specal-Interest 

| Offers »  Greuos (OSIGs), Web-based access to relevant newsgroups, sorted by product, 

i Training « make it easy for you to get information you need to do your job, Take advantage 

of special offers, find useful links, and stay up to date with the latest product and 
technology news. 


MSDM Stores « 


Members Helping Members 


Members Helcing Members (MHM) Is a networking and support tool that helps 
developers get connected, solve problems, and gain recognition within the 
developer community. Get answers quickly by searching the MHM database for 
people who can answer your technical questions, Or, register as a volunteer and 
help other developers when they need it. Sign up now! 


Roaming Profiles 


Sign up for an MSDN Online membership, and we will save your customized 


Figure 3-13: The MSDN Online Member Community Home Page. 


_ MSDN Online Registered Users 


You may have noticed that some features of MSDN Online—such as the capability to 
create a store profile of the entry ticket to some community features—require you to 
become a registered user. Unlike MSDN subscriptions, becoming a registered user of 
MSDN Online won't cost you anything more but a few minutes of registration time. 


Some features of MSDN Online require registration before you can take advantage of 
their offerings. For example, becoming a member of an OSIG requires registration. That 
feature alone is enough to register; rather than attempting to call your developer buddy — 


_ for an answer to a question (only to find out that she’s on vacation for two days, and your 


deadline is in a few hours), you can go to MSDN Online’s Community site and ferret 
through your OSIG to find the answer in a handful of clicks. Who knows; maybe your 
developer buddy will begin calling you with ee eed don’t have to tell ioe where 
hae re getting all your ¢ answers. 
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There are a number of advantages to being a registered user, such as the choice to 
receive newsletters right in your inbox if you want to. You can also get all sorts of other | 
timely information, such as chat reminders that let you know when experts on a given 
subject will be chatting in the MSDN Online Community site. You can also sign up to get 

_ newsletters based on your membership in various OSIGs—again, only if you want to. It’s 
easy for me to suggest that you become a registered user for MSDN Online—l’m a 
registered user, and it’s a great resource. 


_ The Windows Programming Reference Series 


The WPRS provides developers with timely, concise, and focused material on a given 
topic, enabling developers to get their work done as efficiently as possible. In addition to 
providing reference material for Microsoft technologies, each Library in the WPRS also 
includes material that helps developers get the most out of its technologies, and 
provides insights that might otherwise be difficult to find. | 


The WPRS currently includes the following libraries: 


e Microsoft Win32 Developer’s Reference Library 
e Active Directory Developer's Reference Library 
e Networking Services Developer’s Reference Library 


In the near future (subject, of course, to technology release schedules, demand, and 
other forces that can impact publication decisions), you can look for these prospective 
WPRS Libraries that cover the following material: 


_@ Web Technologies Library 

e Web Reference Library 
e MFC Developer's Reference Library 
e Com Developer's Reference Library 


What else might you find in the future? Planned topics such as a Security Library, 
Programming Languages Reference Library, BackOffice Developer’s Reference Library, 
or other pertinent topics that developers using Microsoft products need in order to get 
the most out of their development efforts, are prime subjects for future membership in 
the WPRS. If you have feedback you want to provide on such libraries, or on the WPRS 
in general, you can send email to winors @ microsoft.com. 


If you’re sending mail about a particular library, make sure you put the name of the 
library in the subject line. For example, e-mail about the Networking Services 
Developer’s Reference Library would have a subject line that reads “Networking 
Services Developer’s Reference Library.” There aren’t any guarantees that you'll get a 
reply, but I’ll read all of the mail and do what | can to ensure your comments, concerns, 
or (especially) compliments get to the right place. | 
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CHAPTER 4 


Finding the Developer Resources 
You Need 


Networking is complex, and its resource information vast. With all the resources 
available for developers of network-enabled applications, and the answers they can 
provide to questions or problems that developers face every day, finding the developer 
information you need can be a challenge. To address that problem, this chapter is 
designed to be your one-stop resource to find the developer resources you need, 
making the job of actually developing your application just a little easier. 


Microsoft provides plenty of resource material through MSDN and MSDN Online, and the 
WPRS provides a great filtered version of focused reference material and development 
knowledge. However, there is a lot more information to be had. Some of that information © 
comes from Microsoft, some of it from the general development community, and yet 
more information comes from companies that specialize in such development services. 
Regardless of which resource you choose, in this chapter you can find out what your 
development resource options are, and be more Moree about the resources that are 
available to you. 


Microsoft provides developer resources through a number of different media, channels, 
and approaches. The extensiveness of Microsoft's resource offerings mirrors the fact 
that many are appropriate under various circumstances. For example, you wouldn’t go to” 
a conference to find the answer to a specific development problem in your programming 
project; instead, you might use one of the other Microsoft resources. 


Developer Support 


Microsoft’s support sites cover a wide variety of support issues and approaches, 
including all of Microsoft’s products, but most of those sites are not pertinent to 
developers. Some sites, however, are designed for developer support; the Product 
Services Support page for developers is a good central place to find the support 

_ information you need. Figure 4-1 shows the Product Services Support page for © 
developers, which can be reached at www. microsoft.com/support/customer/develop.htm. 


Note that there are a number of options for support from Microsoft, including everything 
from simple online searches of known bugs in the Knowledge Base to hands-on 
consulting support from Microsoft Consulting Services, and everything in between. 

The Web page displayed in Figure 4-1 is a good starting point from wien you can © 
find out more information about Microsoft's support services. 
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Welcome to Microsoft Product & ort Services for Developers 


voor Guide 


Whether you are a Software or Web Developer, developing or porting 
commercial applications to run on Microsoft platforms requires a unique 
level of support to ensure those applications optimize both current and 
emerging technologies. Microsoft provides access to a wide range of 
product and application development expertise to help developers 
accelerate the development cycle and produce successful applicatians. 
This includes the Microsoft Developer Network (MSDN™) - a specially 
dedicated Web site packed with news, resources and technical services, 


Go to Support Phone Numbers Click here 


PREMIER SUPPORT FOR DE¥YELOPERS 

For large organizations developing products using Microsoft technologies 
who require a direct, proactive and managed support relationship with 
Microsoft, Premier Support offers comprehensive and flexible high-end 
support, 


<> Click here for details 


PROFESSIONAL SUPPORT FOR DEVELOPERS 

Professional Support for Developers provides information services and 
incident-based support to help create and enhance your software 
solutions with Microsoft products and technologies. 


Figure 4-1: The Product Services Support page for developers. 


Premier Support from Microsoft provides extensive support for developers, and 
includes different packages geared toward specific Microsoft customer needs. The 
packages of Premier Support that Microsoft provides are: 


Premier Support for Enterprises 
Premier Support for Developers 

Premier Support for Microsoft Certified Solution Providers 
Premier Support for OEMs 


If you're a developer, you could fall into any of these categories. To find out more 
information about Microsoft's Premier Support, contact them at (800) 936-2000. 


Priority Annual Support from Microsoft is geared toward developers or organizations 
that have more than an occasional need to call Microsoft with support questions and 
need priority handling of their support questions or issues. There are three packages 
of Priority Annual Support offered by Microsoft. 
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e Priority Comprehensive Support 
e Priority Developer Support 
e Priority Desktop Support 


The best support option for you as a developer is the Priority Developer support. To 
obtain more information about Priority Developer Support, call Microsoft at 
(800) 936-3500. | . 


Microsoft also offers a Pay-Per-Incident Support option so you can get help if there’s just 
one question that you must have answered. With Pay-Per-Incident Support, you call a toll- 
free number and provide your Visa, MasterCard, or American Express account number, 
after which you receive support for your incident. In loose terms, an incident is a problem 
or issue that can’t be broken down into subissues or subproblems (that is, it can’t be 
broken down into smaller pieces). The number to call for Pay-Per-Incident SUpPOR 

is (800) 936-5800. | 


- Note that Microsoft provides two Briority technical support incidents as part of the MSDN | 
Professional subscription, and provides four priority technical Support neon as al 
of the MSDN Universal subscription. 


You can also submit questions to Microsoft engineers through Microsoft's support Web 
site, but if you’re on a time line you might want to rethink this approach and consider 
going to MSDN Online and looking into the Community site for help with your _ 
development question. To submit a question to Microsoft engineers online, 

go to support. microsoft. com/suppori/vebresponise. asp. 


Online Resources 


Microsoft also provides extensive developer support through its community of 
developers found on MSDN Online. At MSDN Online’s Community site, you will find 
OSIGs that cover all sorts of issues in an online, ongoing fashion. To get to MSDN © 
Online’s Community site, simply go to msdn.microsoft.com/community. 


Microsoft's MSDN Online also provides its Knowledge Base online, which is part of the 
Personal Support Center on Microsoft’s corporate site. You can search the Knowledge 
Base online at support.microsoft.com/supporvsearch. | : 


Microsoft provides a number of newsgroups that developers can use to view 
information on newsgroup-specific topics, providing yet another developer resource for 
information about creating Windows applications. To find out which newsgroups are 
available and how to get to them, go to support.microsoft.com/support/news. 


_ The following newsgroups will probably be of particular interest to readers of the Active 
a Directory Developer's Reference Library. 
e microsoft.public. win2000.* 
© microsoft.public.msdn.general 
- © microsoft.public.platformsdk.active.directory 
e microsoft.public.platformsdk.adsi 
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microsoft. public. platformsdk.dist_svcs 
microsoft.public. vb. * 

microsoft. public. vc. * 

microsoft.public. studio. *microsoft.public.cert.* 
microsoft. public. certification. * 


Of course, Microsoft isn’t the only newsgroup provider on which newsgroups pertaining 
to developing on Windows are hosted. Usenet has all sorts of newsgroups—too many to 
list—that host ongoing discussions pertaining to developing applications on the Windows 
platform. You can access newsgroups on Windows development just as you access any 
other newsgroup; generally, you'll need to contact your ISP to find out the name of the 
mail server and then use a newsreader application to visit, read, or post to the 

Usenet groups. 


For network developers with a taste for Winsock (and QOS) programming, another site 
of interest is www.stardust.com, which is chock full of up-to-date information about 
Winsock development and other network-related information. There’s other information 
about network programming on the site, so it’s worth a look. 


Internet Standards 


Many of the network protocols and services implemented in Windows platforms conform 
to one or more Internet standards recommendations that have gone through a process 
of review and comments. One especially useful source of information about such 
standards, recommendations, and ongoing comment periods is the Internet Engineering 
Task Force, or IETF. Rather than go into some long-winded (page-eating) explanation 
of what the IETF is, does, and stands for, let me simply say that this is the place where 
networking protocols and other various Internet-related services are often born, 
scrutinized, recast, commented upon, and although not standardized or implemented, 
recommended in a final form called a request for comment, or RFC, even though it’s 
essentially a standard by the time it gets to RFC stage. 


If you want to get a clear technical picture of a given technology or protocol, or if you’re 
inclined to comment on the creation and subsequent scrutiny of such things, the place 
you should go is www.ietf.org. This site can tell you all you want to know about the 
goings on of the IETF, their (non-profit) mission, their Working Groups, and all the 
information you might ever want about almost anything that has to do with networking 
recommendations. | 


If you’re curious about a given protocol or networking technology, and want to find an 
unadulterated (albeit technical) version of its explanation, this is a great place to go. 

It’s a virtual hangout for the brightest people in networking, and it’s worth a look or two, © 
even just for the sake of satisfying curiosity. . 
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Learning Products 


Microsoft provides a number of products that enable developers to get versed in 

the particular tasks or tools that they need to achieve their goals (or to finish their tasks). 
One product line that is geared toward developers is called the Mastering series, and its 
products provide comprehensive, well-structured interactive teaching tools for a wide 
variety of development topics. 


The Mastering Series from Microsoft contains interactive tools that group books and CDs 
together so that you can master the topic in question, and there are products available 
based on the type of application you’re developing. To obtain more information about the 
Mastering series of products, or to find out what kind of offerings the mastering series 
has, check out msdn.microsoft.com/mastering. 


Other learning products are available from other vendors as well, such as other 
publishers, other application providers that create tutorial-type content and applications, 
and companies that issue videos (both taped and broadcast over the Internet) 

on specific technologies. For one example of a company that issues technology-based 
instructional or overview videos, take a look at www.compchannel.com. 


_ Another way of learning about development in a particular language (such as C++, 
FoxPro, or Microsoft Visual Basic), for a particular operating system, or for a particular 
product (such as Microsoft SQL Server or Microsoft Commerce Server) is to read the 
preparation materials available for certification as a Microsoft Certified Solutions 
Developer (MCSD). Before you get defensive about not having enough time to get 
certified, or not having any interest in getting your certification (maybe you do—there are 
benefits, you know), let me just state that the point of the journey is not necessarily to 
arrive. In other words, you don’t have to get your certification for the preparation 
materials to be useful; in fact, the materials might teach you things that you thought you 
knew well but actually didn’t Know as well as you thought you did. The fact of the matter 
is that the coursework and the requirements to get through the certification process are 
rigorous, difficult, and quite detail-oriented. If you have what it takes to get your 
certification, you have an extremely strong grasp of the fundamentals (and then some) of 
application programming and the developer-centric information about Windows Boe 
platforms. 


You are required to pass a set of core exams to get an MCSD certification, and then 
you must choose one topic from many available electives exams to complete your 
certification requirements. Core exams are chosen from among a group of available 
exams; you must pass a total of three exams to complete the core requirements. There 
are “tracks” that candidates generally choose which point their certification in a given — 
direction, such as C++ development or Visual Basic development. The core exams and 
their exam numbers (at the time of publication) are as follows. 
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Desktop Applications Development (one required): 


e Designing and Implementing Desktop Applications with Visual C++ 6.0 (70-016) 
e Designing and Implementing Desktop Applications with Visual FoxPro 6.0 (70-156) 
e Designing and Implementing Desktop Applications with Visual Basic 6.0 (70-176) 


Distributed Applications Development (one required): 


e Designing and Implementing Distributed Applications with Visual C++ 6.0 (70-015) 
e Designing and Implementing Distributed Applications with Visual FoxPro 6.0 (70-155) 
e Designing and Implementing Distributed Applications with Visual Basic 6.0 (70-175) 


~ Solutions Architecture: 


e Analyzing Requirements and Defining Solution Architectures (70-100) 


Elective exams enable candidates to choose from a number of additional exams 

to complete their MCSD exam requirements. The following MCSD elective exams are 
available: | 

e Any Desktop or Distributed exam not used as a core srequiremarl 


e Designing and Implementing Data Warehouses with Microsoft SQL Server 7.0 
(70-019) © 


e Developing Applications with C+ Using the Microsoft Foundation Class Library 
(70-024) 


e Implementing OLE in Microsoft Foundation Class Applications (70-025) 

e Implementing a Database Design on Microsoft SQL Server 6.5 (70-027) 

e Designing and Implementing Databases with Microsoft SQL Server 7.0 (70- 029) 
e Designing and Implementing Web Sites with Microsoft FrontPage 98 (70-055) 


e Designing and Implementing Commerce Solutions with 
Microsoft Site Server 3.0, Commerce Edition (70-057) 


e Application Development with Microsoft Access for Windows 95 and the 
Microsoft Access Developer's Toolkit (70-069) 


e Designing and Implementing Solutions with Microsoft Office 2000 and 
Microsoft Visual Basic for Applications (70-091) 


e Designing and Implementing Database Pppitons with Microsoft Access 2000 
(70-097) 


e Designing and Implementing Collaborative Solutions with Microsoft Outlook 2000 and 
Microsoft Exchange Server 5.5 (70-105) 


e Designing and Implementing Web Solutions with Microsoft Visual InterDev 6.0 
(70-152) | 
e Developing Applications with Microsoft Visual Basic 5.0 (70-165) 
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The good news is that because there are exams you must pass to become certified, 
there are books and other material out there to teach you how to meet the knowledge 
level necessary to pass the exams. That means those resources are available to you— 
regardless of whether you care about becoming an MCSD. 


The way to leverage this information is to get study materials for one or more of these 
exams and go through the exam preparation material (don’t be fooled by believing that if 
the book is bigger, it must be better, because that certainly isn’t always the case.) Exam 
preparation material is available from such publishers as Microsoft Press, IDG, Sybex, and 
others. Most exam preparation texts also have practice exams that let you assess your 
grasp on the material. You might be surprised how much you learn, even though you may 
have been in the field working on complex projects for some time. 


Exam requirements, as well as the exams themselves, can change over time; more> 
electives become available, exams based on previous versions of software are retired, 
and so on. You should check the status of individual exams (Such as whether one of the 
exams listed has been retired) before moving forward with your certification plans. For 
more information about the certification process, or for more information about the 
exams, check out Microsoft's certification web site at www. microsoft.com/train_cert/dev. 


Conferences 


Like any industry, Microsoft and the development industry as a whole sponsor 

conferences on various topics throughout the year and around the world. There are | 
_ probably more conferences available than any one human could possibly attend and still 

maintain his or her sanity, but often a given conference is geared toward a focused topic, 

so choosing to focus on a particular development topic enables developers to winnow 

the number of conferences that apply to their efforts and interests. 


MSDN itself hosts or sponsors almost one hundred conferences a year (some of them 
are regional, and duplicated in different locations, so these could be considered one 
conference that happens multiple times). Other conferences are held in one central 
location, such as the big one—the Professional Developers Conference (PDC). 
Regardless of which conference you're looking for, Microsoft has provided a central site 
for event information, enabling users to search the site for conferences, based on many 
different criteria. To find out what conferences or other events are going on in your area 
of interest of development, go to events.microsoft.com. — ? : 


Other Resources 


Other resources are available for developers of Windows applications, some of which 
might be mainstays for one developer and unheard of for another. The list of developer 

- resources in this chapter has been geared toward getting you more than started with 
finding the developer resources you need; it’s geared toward getting you 100 percent of 
the way, but there are always exceptions. 
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Perhaps you’re just getting started and you want more hands-on instruction than MSDN 
Online or MCSD preparation materials provide. Where can you go? One option is to 
check out your local college for instructor-led courses. Most community colleges offer 
night classes, and increasingly, community colleges are outfitted with pretty nice 
computer labs that enable you to get hands-on development instruction and iecaaele 
without having to work on a 386/20. 


There are undoubtedly other resources that some people know about that have been 
useful, or maybe invaluable. If you know of a resource that should be shared, send me 
e-mail at winors @ microsoft.com, and who knows—maybe someone else will benefit 
from your knowledge. 


If you’re sending mail about a particularly useful resource, simply put “Resources” in the 


_ subject line. There aren't any guarantees that you'll get a reply, but I'll read all of the mail 


and do what | can to ensure that your resource idea gets considered. 
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CHAPTER 5 


Understanding Remote Access 
Transmission Technologies 


First things first: This chapter is not absolutely necessary to develop programs that make 
use of RAS or the remote access capabilities of RRAS. But then again, you don’t need 
an electrician’s certification to play with circuit breakers and wiring (but the knowledge 
that goes along with that certification can really help). The point is that garnering a 
knowledge base for the technologies associated with your work (whether it’s developing, 
plumbing, or electrical work) can go a long way in helping you better understand what 
you're working with. 


This chapter is geared toward providing you with a quick, reasonably concise 
explanation of the transmission technologies associated with remote access. Of course, 
there are likely going to be improvements and changes to these technologies as time | 
marches on, but from this basis, you will be better prepared to understand those | 
changes. How can this chapter help you develop better applications? If you’re doing the 
debugging or testing of your applications, these can help tremendously; is it your 
application that isn’t working properly (or providing the best performance), or is it the fact 
that your 56k modem is actually achieving only 33kbps (because noisy lines can make 
modems drop in their transmission rates to achieve a reliable connection)? Is ATM a 
telephone technology for Regional Bell Operating Companies (RBOCs), or is it a network 
transmission technology (see the ATM section later in this chapter)? Knowing the 
answers to questions such as these (and many more) can make you a more savvy 
remote access developer, and might even expand your knowledge base a bit, which is a 
worthy achievement in its own right. 


Analog Modem Technology 


Analog modems make up the bulk of the long-distance computer communications 
devices today. These modems are analog because we live in a world (or a time) where 
the most widely available network—the telecommunications network—is based almost _ 
entirely on analog connectivity for the end user (this is changing with ADSL and Cable 
Modems, but it has a long way to go). | 
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As most of you know, however, computers don’t function natively on analog signals; — 


_when the computer is communicating internally between subsystems, such as when the 


hard drive is loading an application into memory, it doesn’t communicate with analog 
data. The computer instead functions on digital data (ones and zeros), requiring some 
means of converting the digital information on a computer into a form that can be 
transmitted over the analog device connected to the telephone network. The devices 
used to achieve this transition are today’s analog modems. 


What is a modem? Most people can point one out in a lineup, but actually answering 
what a modem is, what it does, how it does what it does, and where it got its name are 
generally not too clear. Quick answers: Modems are communications devices that use 
the telecommunications network to transmit data over geographically distant sites. 
Modems take digital signals (from the computer) and turn them into analog signals that 
can be transmitted over the telephone network. Modems do this by taking the serial data 
they receive from a COM port and translating it into specific analog signals that can be 
understood by the modem on the other side of the connection and translated back into 
digital data. Modem stands for MOdulator/DEModulator. 


Getting Data to the Modem 


It’s late at night and you have a sales information file on your hard drive at home (which 
is where you are for this illustration), which absolutely needs to:be on the company 
server before the day ends. That means you need to get the sales information file from 
your computer at home to the server at work, and that’s going to be achieved when you 
make the connection between your modem and one of the modems hanging off the | 
RRAS Server at corporate headquarters. What does that mean? It means that you need 
to get the data from your hard drive to the modem, then the modem needs to send it. 
over the telecommunications network (PSTN, from here forward) to the corporate 
modem, which will then forward it appropriately to the server to which you're trying to 
transfer the file. Nothing to it. 


Parallel Versus Serial Communication 

A computer communicates in parallel communication, which means that it sends multiple 
bits of data at once. Serial communication, in contrast, sends one bit at a time. Think of it 
this way: When you go to Disneyland or one of the Six Flags theme parks, at the front 


gate there are a number of turnstiles that funnel incoming guests through the ticket gate. 
_ If there are eight turnstiles, wnen looked at as a whole, they are letting people through 


the gates eight people at a time. So you have eight lines, and if the ticket-takers are 
synchronized (taking tickets at precisely the same time), PEO would be entering the 
park eight people at a time. 


Serial communication, in this example, would be like a theme park that had only one- 
turnstile, and thus could let people come through the gale only one at a time. 
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Because your computer's bus utilizes parallel communication to send data wherever it’s 
going around the computer, and the communications port needs to communicate ~ 
serially, there must be a means by which the computer's parallel means of 
communication and the serial port’s serial means of communication are translated for 
one another. This is done by a chip called a Universal Asynchronous 
Receiver/Transmitter (UART). Each communications (COM) port on your computer also 
has a UART associated with it, which translates parallel data to serial data, and vice 
versa. Figure 5-1 illustrates the mechanism. 


To Computer Bus To COM (serial)Port 


aa 


Parallel Data 
| Changed to Serial 


Serial Data 4” 
Changed jo Parallel 


Figure 5-1: Parallel Data Going Through the UART to the Communications Port, 
and Vice Versa. 


Part of the responsibility of the UART is to add (upon transmission to the COM port) and 
remove (upon reception from the COM port) start and stop bits that “frame” serial data to 
let the receiver of the data know when the beginning and end of a byte’s data is reached. 
In very loose terms, a start bit is similar to the capitalization we do at the beginning of a 
sentence and the stop bit is similar to the period we put at the end of a sentence. 
Without either, it would be much more difficult for us to determine where a sentence 
starts and where one ends; though we may be able to figure it out from context, there is 
still room for ambiguity and computers don’t have much tolerance for such inaccuracies. 
The start and stop bits in a sentence let us read more clearly, understand much better, 
and are universally (in English, at least) accepted delimiters. The same can be said for 
Start and stop bits in serial communication. | : 


All UARTs are not created equal. Some are better than others, some are faster than 
others, and some still are faster and better than all the others—and of course, generally 
more expensive. Internal modems use a UART that comes built into the modem card 
itself and thus doesn’t utilize the UART (or COM port) built into your computer. 
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Whether this is good news or not is largely a matter of opinion, but Know that you are at 
the mercy of the modem manufacturer for the quality of your internal modem’s UART, 
which means that there is another performance parameter to take into consideration 
when purchasing your internal modem (if you do such a thing—I wouldn’t suggest it). For 
the rest of this example, I'll presume you have an external modem. 


Back to the sales file. You’ve instructed your computer to send it to the corporate LAN 
(I’m presuming at this point that you’re connected to the corporate LAN using your 
modem) and now the UART on your computer is taking the data that the hard drive is 
sending over the bus (the computer’s internal freeway system for its data) and 
translating it from the computer's native parallel form of communication to serial 
communication—in other words, to the COM port. Your modem, then, is connected to 
your COM port and is accepting the serial data from the COM port. Your modem takes 
this serially transmitted data, looks at it, maybe compresses it if that’s part of its 


_ functionality/feature set, and then sends it out over the wire and across the PSTN. This, 


of course, is where the modem’s laws of physics kick in. 


How Analog Modems Operate 


How were all of these analog transmissions achieved, once this data got to the modem? 
How did modem makers go from 300bps—that’s bits, not bytes, per second—to almost 
200 times that throughput? It all has to do with the means by which they modulated the 
data, and an explanation of how such modulation is done requires more than a cursory, 
narrative description of how modems came into being and took their permanent place at 
the PC dinner table. That explanation requires an overall view of the means by which 
modulation is achieved, the constraints under which modems must function (dictated by 
the PSTN), and the means by which these conditions are married in today’s 
contemporary modems. In short, such an explanation requires details. Only after these 
details are fleshed out will we see why the bandwidth available for the analog modem is 
EOnING out. 


PSTN Bandwidth — 


I’ve already mentioned the confines within which modems connect to the PSTN, but here 
we're going to look a little closer and throw in a couple of illustrations to show just where 
these lines are drawn. 


Remember that the PSTN was built around the need to provide voice service to the 


_ masses. Two terms are important in that statement: “voice” and “masses.” When the 


infrastructure of the PSTN was being created and the decision regarding how much 
bandwidth to provide was made (and where that bandwidth was on the analog 
spectrum), economics ruled, as they probably should have. A certain level of quality was 
necessary, but to provide crystal-clear voice transmissions wasn’t the goal; the goal was 
to provide voice service to the masses, and that meant having the capability to transmit 
massive amounts of calls over the PSTN infrastructure all at once, or at least a lot of 
them at once. 
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It was found that the range of analog signals necessary for transmission of intelligible, 
reasonably clear communicated speech could be constrained to the range of 300 to 

_ 3300 Hz. Such constraint provided for an economy in the transmission of lots of these 
voices because the more range provided, the more bandwidth necessary for 
transmission over the PSTN infrastructure. The range over which the transmission of 
voice was allowed to transpire was set, and the equipment that handled voice traffic 
(switches) filtered everything below and above this set range. The result was an 
available range similar to what you see in Figure 5-2. 


—_— Approximate Range of Human hearing sense 
Benner REPTOGUCION Range of Stereo Speakers ammannbieercsssevsend 


»« Available PSTN Transmission Range 


1,000 2,000 3000 4,000 5,000 19.000 


300 3,300 | 20,000 


= PSTN Filtering 


Figure 5-2: The Range Available for Voice Transmission Over the PSTN. 


This worked great for the telecommunications network—it could limit the amount of 


resources necessary to transmit voice from one end of the network to the other—but the | : 


same factor that provided an economy of transmission for the telecommunications 
network also bridled the amount of theoretical bandwidth available for the transmission | 
of data. In short, PSTN filtering limits the amount of bandwidth available to o analog 
modems. 


Modulation 


Modulation is the conversion of digital data into tones, or arialo form. For example, 
when you put the receiver to your ear and hit a number key on the telephone, a certain 
and specific tone is emitted for as long as you hold down that number. On the receiving 
side of things (the PSTN), the tone is recognized as the representation of a number (the 
number of the key you pressed), and as those numbers are pressed, the phone 
company knows that your intent is to connect to another telephone and it puts the signal 
through. Modems do much the same thing, except that the tones that they emit are 
going much, much faster than your finger can press, and the means by which they 
generate these tones (as well as the way the present certain characteristics of the tone, 
such as its phase) follow a set of standards that all modems understand and translate 
into data. The three major means by which analog modems throughout their existence 
have transmitted their data are Frequency Modulation (FM), Amplitude Modulation (AM), 
and Phase Modulation (PM) or Phase Shift Keying (PSK). 


Aword of warning: A true, complete, and in-depth technical treatment of modem 
modulation is the subject of an entire book, not one chapter’s section. I'll give you a good © 
overview and enough information and explanation to help you understand how it works. - 
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If you want more specifics, more mathematical depth, or just more bulk, there are 
technical papers and telecommunication tomes in abundance that can articulate what 
equations were used to get where we are today. This is the hands-on version; the 


“pencils-on” and “calculators-on” versions can be found at your local university bookstore 


in the “in-depth treatment of technical telecommunications theories” section. 


Modulation methods | 
FM, utilized in early modems, implements a changing of the carrier frequency (i.e., the 
analog signal, or sine wave) to represent the value of the bit being transmitted. For 
example, if we use a frequency of 1070Hz to represent zero, and a frequency of 1270Hz 
to represent one (remember that we must operate in the 300Hz to 3300Hz range or the 
PSTN will filter us out), then we can switch between these two frequencies and transfer 
data. If the baud rate is 300, which means that the signal can change 300 times per 
second, and with each change we communicate one bit of information, then the bit rate 
is equivalent to the baud. If this is the case, then we also know—because a baud rate of 
300 means that there are 300 signal changes per second—that the duration of one of 
these little pieces of information is 1/300th of a second. Figure 5-3 presents a visual 
representation of FM. 


Frequency Modulation 


4/300th 47300th 4/300th 1/300th 1/300th 1/300th 1/300th 41 (300th 1/300th 1/306th 47300th 1/300th 
Time (in seconds) 


WN =4 Nf\y =0 300 baud, 300 bits/second — 
Figure 5-3: Frequency Modulation. | | 


Though FM was used in some modems that operated at higher speeds than 300bps, in 
contemporary modems FM has been replaced by a combination of the two following 
approaches. | 


AM achieves the transmission of zeros and ones through the use > of a change i in the 
amplitude, or height, of the analog signal. Figure 5-4 puts this into a picture. 


As you can see from Figure 5-4, AM uses a change in the amplitude of the analog signal 
carrying its information to create the distinction between ones and zeros. If AM is 
straightforward and easy to comprehend, then the third means to impress intelligence on 
an analog signal (or in simpler terms, to transmit data using an analog signal), PM, 
makes up for it. 
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Amplitude Modulation 


1/300th 1/300th ==: 1/300th 1/300th = 1/300th 1/300th 4/300th 1/300th 14300th 1/300th 1/300th 1/300th 


Time (in seconds) ) 
WW =1 “Ny =0 300 baud, 300 bits/second 


Figure 5-4: Amplitude Modulation. 


PM changes the phase of the sine wave being transmitted in order to represent a value. 
PM is certainly best explained with a picture (Figure 5-5) and | think a thousand words | is 
on the low side. , 


Phase Modulation 


1 baud 1 baud 1 baud 1 baud 1 baud 1 baud 1 baud 1 baud 1 baud 1 baud 1 baud “Tbaud | 


Time (in seconds) anon s 


Figure 5-5: Phase Modulation. 
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PM is reserved for more sophisticated modems, generally those that are 14,400bps and 
above, which puts most (or all) of our contemporary modems in the category of PM, also 
knows as PSK. As mentioned earlier, AM and PM are often combined, the result of 
which is that a single signal can represent more than one bit. More on that later. First, 
let’s take a look at what a simple modulation scenario, using a modem that pemenrs 
FM, might shake out to be. 


Simple modulation 


In terms of implementation and explanation, the simple version of modulation comes 
when the bit rate is equal to the baud. This hasn’t been the mode of operation since 
early in the 2400bps/baud modem days, but it is the building block of more complex 
modulation methods, so the discussion appropriately starts here. 


We already know what bits per second is—the amount of bits (ones or zeros) that can be 
transmitted in a given second—but we haven't really clarified baud. This is a perfect 
point at which to clarify. 


The term baud is defined as the number of signal changes for an analog transmission in 
a given second. In early modems, the baud rate was equal to the bits per second rate, 
because each change in the analog signal (actually a sine wave) represented one bit. 
From our earlier explanation of FM, we were talking about a modem that transmitted 
zeros with a signal setting of 1070Hz, and transmitted ones with a signal setting of 
1270Hz. In the simple version of modulation, a zero will be communicated across the 
PSTN by transmitting the carrier signal at 1070Hz for the duration allotted once signal 
value (that’s 1/300th of a second on a 300 baud modem). If the next bit to be transmitted — 
is also a zero, the carrier signal will continue at the frequency that corresponds to zero 
(1070Hz) for the duration of another signal value (another 1/300th of a second). This is 
very straightforward, and as Figure 5-6 suggests, the mapping of single bit to each signal 
change makes for an easily understood scenario. 


Specific Frequencies = 0 or 1 


100th = 1/800th_—1/300th_ = 1/800th_ = 1/800th = 1/800th = 1/300th_ = 1/300th = 1/300th_ = 1/800th = 1/800th_—1/800th 


AVAV, =1070 Hz (represents binary 0) 
ATTATF =1270 Hz (represents binary 1) 


Figure 5-6: Mapping One Bit for Each Baud. 
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But in real life, things are rarely that simple. The next section explains the more complex 
version of analog modem modulation. | 


Complex modulation 


To respond to the increasing need for speed, modem manufacturers developed a way to 
transmit more data through the same (finite) baud rate available through the analog 
PSTN. In other words, they figured out how to transmit more than one bit for each signal 
change. Of course there were some acronyms that evolved from such ideas; dibit 
encoding deals with the encoding of two bits per signal change, tribit encoding involves 
allowing each signal change to represent three bits (imagine that). There’s also the 
venerable QAM, or Quadrature Amplitude Modulation, which results in four bits being 
transmitted for each signal change (QAM32 and QAM64 are variations of QAM that 
represent five and six bits respectively). These days, however, bit transmission rates are 
in the nine bits per signal change neighborhood for analog modems. 


This mapping of more than one bit per signal change is generally achieved through the 
combination of PM or PSK (PM/PSk) and AM. But a little bit of explanation is required 
for a reasonable amount of understanding to be achieved with regard to how this 
mapping is done; it isn’t quite as straight-forward as it sounds at first pass. QAM, with its 
four bits per signal change operation, requires 16 distinct states. 16? Yes, because as 
you remember, we're talking about the representation of binary information, and for all 
possible combinations of four binary bits to be provided, there must be 16 states. Look at | 
Figure 5-7. 


As you increase the amount of bits you want to transmit with each signal change, the 
number of discreet states that must be available to represent every available bit 
combination grows in a binary fashion. In other words, the amount of discreet states that 
must be represented doubles every time you add one bit to the number of bits you’re 
trying to transmit with each signal change. With QAM, which represents four bits per 
signal change, you need 16 (24) discreet states; if you want to send five bits per signal 
change, you need 32 (25) discreet states. Once you get to 9 bits, you need 512 (29) | 
discreet states. That’s a lot of states; too many to transmit on conventional PSTN lines 
without lots of errors, actually. As the states increase, the difference (in amplitude or 

_ phase shift) between the states becomes smaller and smaller, until you get to the point 
where the state changes are so susceptible to noise in the line—noise that can attenuate 
the signal and thus make it appear changed once it gets to the receiver—that the 
transmission becomes error laden to the point that the use of so many signal states 
becomes its own worst enemy. A better way to manage errors was needed, and in order — 
to get past the 14,400bps modem speed with any consistency, it was absolutely 
necessary. That better way came in the form of Trellis Coding. | 
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4 binary bits represent 16 distinct values... 


: _ Bit values are cumulative. If two bits are set, 
_ simply add their values to get the numeric value 
from its binary representation. 7 


The first bit (if set, or =1) has a value of 1 
First Bit The second bit (if set, or =1) has a value of 2 
Second Bit : The third bit (if set, or =1) has a value of 4 


Third Bit | The fourth bit (if set, or =1) has a value of 8 
Fourth Bit . 


16 possible values 
0000 
0001 
0010 
0011 
0100 
0101 
0110 
0111 
1000 
1001 
1010 
1011 
1100 
1101 
1110 
1111 


When we combine PSK and AM, then, we can efficiently create 16 distinct states. PSK accounts for 
the first two bits, AM accounts for the second two bits; together, they form a four bit series of data. 


PSKValue 01 00 104 tsi isi tS 
AMValue 01 71. 00s OT 1 Ot wt 0 


Binary Value (PSK+AM) 0101 0011 1000 1101 1011 4101 0010 0001 0101 1101 0010. 


PSKiPhase Modulation) Le end: 3 


Figure 5-7: Four Binary Bits Being Represented as 16 Changes. 


Chapter 5 Understanding Remote Access Transmission Technologies 47 


Trellis Coding is a method of encoding data that is much more robust than conventional 
QAM encoding; Trellis Coding can tolerate more than twice as much noise or other line 
imperfections as QAM modems, and its sophisticated error detection techniques reduces 
the likelihood of transmission errors by orders of magnitude. The decrease in errors is _ 
achieved by adding redundancy into the bit stream that essentially “steers” the 
interpretation of the received signal to the correct value. In Trellis Coding, only certain 
sequences of ones and zeros are valid. As the data stream passes through the Trellis 
coding logic, its bit sequences (zeros and ones) are evaluated and then impressed with 
redundant bits and sent over the wire. When the transmission reaches its intended 
receiver, the value is sent back through the receiving modem’s Trellis Coding logic and 
checked for “Trellis Coding” validity, and then handled applennaely (rejected or 
passed). 


Today’s modems transmitting at 33.6kbps use Trellis Coding and other techniques such 


as equalization (built-in components that compensate for channel distortion) to get all 


sorts of data across the wire. We've hit the major points here. 


The bottom line, then, is that contemporary modems take the synchronous bits (received 
through the COM port via the UART, which has converted the parallel data from the 

- computer into serial data that the modem can understand) and group them into multiple 
bit groups (often groups of nine), then represent that group of bits by choosing the | 
unique signal state (through a combination of AM and PM) that corresponds to that 
specific group of bits, then transmits that unique signal (and thus the bit group) within a 
single cycle. To avoid errors—errors that would certainly result from the closely aligned 
constellation patterns of today’s modems—contemporary modems use the complex 
mathematical formulas and encoding logic incorporated in Trellis waa to greatly 

| reduce the chance of mistaken signal state identity. 


The 56k version — 


56k technology takes even the reduced Trellis Coding mistaken signal-state identity 
_ problems to task. This analog modem technology, which is actually a hybrid digital- 
analog technology, comes in the form of a touted but mostly untrue 56 {000bps 
downstream throughput technology commonly referred to as 56k technology. 


56k technology is based on the fact that most remote access service providers, such. as 
an MSN or an ISP, or many mid-sized or larger corporate remote access facilities, have 
digital T1 connections servicing their modem banks. This digital connection, the T1 
servicing the server modems, is critical to the implementation of 56k technology, for it 
ensures that only one digital to analog conversion will occur in the path between the 
server modem and the client modem and removes all errors associated with degraded or 
distorted analog signals on the server modem’s loop. Notice here that we can specify, or 
define, server modem and client modem: The server modem is the 56k modem that is 

- directly attached to the digital T1 facility, while the client modem is the 56k modem that is 
attached to the user’s standard analog subscriber loop. Notice also that both modems 

~ are 56k modems, which is a prerequisite for establishing 56k connections. Figure 5-8 
shows how the physical setup of this configuration would look in terms of the elements 
involved in ergating the connection between modems. 7 : | 
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PSTN = Public Syaiched Telephone Network, 


or the Telecommunications network 


Digital to Analog © = 156k Modem Bank 
Conversion 


wei — Downstream 56k Digital Data Transmission 


Figure 5-8: The PSTN, with a Remote Access Provider Connected to a T1 and a 
Client Connected to the Telephone Line. 


The effects of this isolation of digital to analog conversions provides the means by which 
56k technology can be implemented. The PSTN digitizes transmissions when coming 
from the analog subscriber loop, or in more widely used terms, does an analog-to-digital 
conversion of the data. The information travels across the digital core PSTN until it 
reaches the Central Office (CO) servicing the receiving connection’s subscriber loop, 
where the digital information that has traversed the PSTN is turned back into analog 
form. | 


56k technology removes the initial analog-to-digital conversion, creating a 
communication between modems that contains only one conversion—that which occurs 
as the digital information sent from the server's 56k modem reaches the client modem’s 
subscriber loop, where it is put into analog form. There are 256 possible representations 
of analog information (8-bits per sample, which in binary creates 256 possible 


_ representations); the 56k server modem uses that knowledge to its advantage by 


transmitting those specific codes. By avoiding the analog-to-digital conversion, and thus 
avoiding the Analog to Digital Converter’s (ADC) interpretation of analog signals that — 
may have been distorted or attenuated by line noise, server modems equipped with 56k 
technology can transmit the binary representations of the analog signals, thus avoiding 
all errors associated with the first analog loop. 
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Although not all of the 256 representations can be utilized, largely because as they 
approach OHz the space between those analog representations of digital data is too 
small and thus too prone to errors with even the smallest line noise (line noise is still an 
issue on the client modem’s subscriber loop), many of the 256 representations can be - 
utilized and discretely transmitted to and through the Digital to Analog Converter (DAC) 
to the client. It is digital all the way to the client subscriber loop DAC, and due to that 
fact, errors and limitations resulting from what would be the server’s analog-to-digital 
conversion are removed, allowing throughput levels that approach the absolute ceiling of | 
DSOs (Digital Signal level 0), the individual analog line payload, 64kbps. | 


ISDN Technology 


First a quick disclaimer: ISDN technology is not analog modem technology, but its 
discussion as a (waning) client-end transmission technology meant its discussion fit 
better here (in this section) than in any of the others. Disclaimer complete. 


You’ve probably heard of ISDN, and depending on whom you were listening to, probably 
heard how it will never get off the ground, or how it’s noticeably way, way faster than 
even 56k technology. In remote access connectivity reality, both may be correct. The 
technology has drawn praise and prejudice, and along the way pro tem meanings have 
been coined to usurp the official acronym, such as ISDN standing for “I Still Don’t Know.’ 
Whoever thought that one up obviously wasn’t a spelling bee champion. 


ISDN actually stands for Integrated Services Digital Network, and its most notable 
technological departure from today’s analog modems is easily explained: ISDN removes 
the analog part of the data transmission process. There is no analog local loop; it is 
instead all digital, and that digital connection enables users to achieve the full 64kbps 
per channel that T-Carriers and ISDN PRI frames offer to each channel every 125 
microseconds, thanks in part to its technological design that puts signaling and 
administration features out-of-band. I’ve loaded this paragraph with plenty of 
unexplained technology tidbits; let’s get to the explanation part of it. : 


First, the all-digital part. Telephone lines are analog, so they can take your voice (an 
analog signal) in its native format (as you talk into the phone) and do their conversion 
from its natural analog form into digital form so that the PSTN can send the © 
representation of your voice over the PSTN infrastructure in an efficient way. With ISDN, 
you Call up your local telephone company and say, “I'd like ISDN.” If ISDN service is 
available in your area, and once all the details of getting the service are ironed out, your 

— telephone line (or your extra line) is physically changed at your CO to an ISDN interface, 
and in effect, the analog-to-digital converter that is on everyone else’s line is removed. 
To clarify this, take a look at Figure 5-9. | 
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Before ISDN... 


Analog Subscriber Loop 


After ISDN... 


Digital Subscriber Loop | 


Analog conversion of digital 


data no longer takes place at the 

Central Office; the digital information 

is put into ISDN format and sent 

along to the customer’s line unmodulated, 
or, as digital information. 


Figure 5-9: An Original Analog Line Getting Changed to an ISDN Line. 


On to the second point: ISDN provides the ability to utilize the entire 64kbps channel 

_ provided by the T-Carrier/ISDN PRI standard. Explanation of this brings us back to the 
digital end-to-end characteristic of ISDN. Through such digital implementation, the need — 

— to interpret analog information and translate that analog information into its binary | 

_ representation is removed. What that leaves, then, is the ability to use all 8-bits of the 
per-cycle sample for data (still accomplished at 8,000 samples per second, or in 125*s 
intervals. This is a trend you will see throughout telecommunications and its new 
technologies). 8,000 samples * 8-bits per sample = 64,000 bits per second, per channel. 


ISDN comes in two standard interfaces: Basic Rate Interface (BRI) and Primary Rate 
Interface (PRI). | 
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BRI is geared more for the end user or small company, and its standard offering is two 
bearer or B Channels, each operating at 64kbps as explained earlier, and one data or D 
channel. This configuration is often referred to as 2B+D. The B channels handle the data 
(or voice, video transmission, or whatever other ISDN-featured technology you want to 
use the channel for), while the D channel manages the administrative part of the ISDN 
service suite. 


PRI is geared toward the remote access service center, or PBX, or other multi-line (the 
term is being used loosely here) services planned for the ISDN PRI interface. PRI is 
similar in use to a T1 in that it can support multiple remote access sessions through one 
interface. PRI also has a bandwidth of 1.536Mbps, as does a T1, but its division is | 
slightly different than that of a T1. The PRI is generally divided (in remote access 
solutions) into 23 64k B channels and one D channel. Thus the PRI is the ISDN interface 
that would be used at the corporate RRAS/remote access site to provide ISDN © | 
connectivity to remote users. , 


ISDN is more complex than conventional modems. Its implementation requires more 
patience, especially since you can’t just plug into your existing phone line and call it 
good. And with the availability of ADSL or Cable Modems these days (both of which . 
provide much more Panceaah), i's a hard sell to just about anyone. . 


Residential Broadband Technology 
ADSL Technology 


What’s one of the biggest financial assets of the telecommunications industry? The 

~ existing wiring plant; all those pairs of twisted wire running under the ground of almost 
every street in America, bringing a dial tone to anyone who wants it and everyone who 
needs it. It’s everywhere, and it’s a huge asset. It’s in everyone’s home, everyone’s 
business, and in many places, there’s more than one pair of wires to each residence. 
That’s a lot of contact with a lot of people, and those people want a lot of bandwidth for a 
lot of different reasons. The telephone companies want to provide that bandwidth, | 
however it gets to you. What’s perhaps the best way to do so? Well, | suspect using an 
existing, omni-present, already-paid-for telephone wiring infrastructure would be a good 
means of providing high data-rate services, at least as far as the local telephone — 
companies are concerned. The problem lies with their wiring: Standard twisted pair 

_ wiring, the kind that everyone has in their house, was meant for voice, not high-speed 
data services. The telephone companies thought (and said to Bell Labs, now Lucent), 
“what if we could use that existing wiring infrastructure to provide high speed data 

: services?” Enter ADSL. | 
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ADSL stands for Asymmetric Digital Subscriber Line, and its technology is the result of a 
search to find a way to utilize existing copper twisted-pair wiring—standard phone 
lines—to provide a high bandwidth solution. It has had a few (too many) acronyms, 
including HDSL, SDSL, RADSL, VADSL and VDSL, and although some of these 
acronyms stand for differing applications of the overall DSL technology, ADSL has 


emerged the most widely known, likely because it’s the most used application of xDSL. 
The reason for its wide use (in terms of xDSL technologies) is that ADSL’s distance 
requirements encompass the majority of existing telephone lines, and because it has the 
potential to be deployed in large volume in the near future. VDSL is actually a higher- 
throughput rate of ADSL; differentiation and explanations of the differences between 
them and the other xDSL technologies will be covered in the following section. 


ADSL Technology Overview 


As the term “Asymmetric” suggests, ADSL technology provides different throughput 
levels for each direction, or in more direct terms, ADSL can pull data downstream at a 
much higher throughput rate than it can send data upstream. 


ADSL’s theory is relatively straightforward in its explanation: Through the use of a 
modem pair, one at the customer premise and one at the local CO, data is transferred at 
very high speeds to the customer premise equipment (downstream). A lower level of 
bandwidth is afforded for the upstream communication, but the ratio is very much in the 
downstream favor (for example, 756kbps downstream : 128kbps upstream), which 
coincides perfectly with the way people use their residential services. Audio and/or video 
content such as movies (incoming, or downstream), Internet access (Web page viewing 
is mostly downstream), and radio (downstream, and reproduced with great clarity if it’s 
digital) are all downstream content deliverables, and these are just some of the more 
obvious examples. 


One of the most attractive aspects of ADSL is the fact that it incorporates the use of your 
existing telephone line into its technology, which means you need only one telephone 
line to keep your existing unmodified (as far as you can tell) telephone service, and you 
get the full range of bandwidth associated with ADSL without any conflict. People in the 
household can be on the telephone, surfing the Web, listening to some heavy metal 
radio station, watching some on-demand movie, and playing an interactive Internet- 
based Quake Arena deathmatch, all at the same time with ADSL. No more obnoxious 
data signals or interrupted transfers because someone picked up the phone when you 
were getting a fax or sending e-mail. The setup of ADSL in the home looks similar to 
Figure 5-10. 


ADSL’s technical implementation is somewhat more complex, but because we’ve | 
already been through analog modem explanations, it will be much easier to explain and 
understand. 
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Other Data 
Services... 
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Figure 5-10: ADSL in Simultaneous Use in the Home. 


We remember that standard telephone service uses the 300Hz to 3300Hz frequency 
range for telephone calls; for more practical reading, we'll simply say that standard 
telephone services uses frequencies between OkHz and 4kHz (OHz and 4000Hz—some 
_ of the frequency spectrum above 3.3khz is used for administrative purposes). As stated 
previously, data within that spectrum is digitized and passed along the circuit toward its 
destination and any signal or information above that range is filtered out at the local CO. 
This is why standard analog modems have such constraints under which they must 
operate, since all the data they want to transmit must be sent within that frequency 
range, as it otherwise would be filtered out and never reach its destination. | remember 
thinking, “why don’t they just do away with that filtering and allow for more use of the | 
frequency spectrum?” Guess what: ADSL technology does away with that filtering. © 


By removing the constraints of the standard PSTN filtering, ADSL can appropriately 
divide the resulting available spectrum among standard telephone service, data service, 
video-on-demand service, radio service, and whatever other services come along. 


With all this high-throughput talk, there is one very important consideration to keep in 
mind when touting the benefits of ADSL or any xDSL technology: It is distance-oriented, 
and the greater the distance between the residence and CO, the lower your maximum 
throughput. There are limits to the frequency at which ADSL or any xDSL modem can 
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operate due to attenuation and other physical characteristics that degrade the signal as 
it ttavels down the twisted pair wire. These signal losses or distortions, and their 
aggregated effects on the signal being transmitted between modems, result in the 
distance limitations placed on throughput capabilities of ADSL. Longer wire runs mean 
more signal distortion or loss, and as the wire gets shortened these effects are. 
minimized, leaving more frequency range available for transmitting data. There are some 
ADSL implementations that attempt to adapt to imperfections in the attached telephone 
line, such as Rate-Adaptive ADSL (RADSL), which tests the line for noise or 
transmission impairments and adjusts its transmission to get the most throughput 
possible out of the available line quality (a great advantage of ADSL technology, IMHO). 
Despite this adaptation to the noise inherent with telephone lines, ADSL is still sensitive 
to line distances; the shorter the distance the better. Thus, shorter distances provide 
greater available bandwidth, and that discussion brings us to VDSL. 


VDSL or Very high data rate Digital Subscriber Line, sometimes called VADSL when 
“Asymmetric” is thrown into that line of words, can be called the short, stocky cousin of 
ADSL. In short (excuse the pun), VDSL is a very high-speed version of ADSL. Though 
sometimes called VADSL, it is inaccurate at this early stage in the game to presume that 


~ VDSL will be asymmetric. Indeed, though maximum line lengths would be compromised 
in the process, it is possible that customers who would need the extremely high VDSL 


data rates would want (and get) symmetric service; in other words, those customers 
would want the high throughput in both directions of the connection. 


The question then becomes: How does ADSL get all that information from one modem to | 
the other? There are two technological camps with regard to which method is better, and 
those are CAP and DMT. 


CAP stands for Carrierless Amplitude/Phase modulation, and is essentially a variant of 
QAM, which was discussed earlier in this chapter as a means of representing multiple 
bits with one signal change. CAP was not in the ANSI T1.413 standardization for ADSL 
technology, but success in its implementation in some field trials have reportedly 
resulted in some big name manufacturers of ADSL eH pypent lobbying for its inclusion in 
the ANSI standard. 


DMT stands for Discrete Multi-Tone. DMT (in general terms) effectively divides the 
available frequency spectrum into discrete frequency segments, each of which (or many 
of which, for certain segments) is specifically allocated in its ADSL application for certain 
uses such as video channels, ISDN channels, or administrative signaling, which also 


reserves existing frequency ranges for standard telephone service. Often these 


segments are called channels. DMT is included as the standardized ADSL transmission 


~ technology in the ANSI T1 -413 recommendation. 


ADSL technology, though somewhat easy to explain in its theoretical and 
implementation approaches, is certainly not a simple feat of engineering; it is a genius of 
invention and implementation in its hardware and the algorithms that go into the innards 


ofan ADSL modem, and we’re fortunate enough take be able to take it for granted. 
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Cable Modem Technology 


Cable companies also have a very large, very valuable installed infrastructure base, 
though it differs widely from the installed telecommunications base, as we'll investigate 
further when we discuss the technology behind cable modems. One differentiating - 
feature of cable modem technology, however, is that cable modem technology has lots 
of potential bandwidth on which it can operate. How much? More than a T3. More than 
your Fast Ethernet can handle. More than an OC-3. More than an STS-5. Lots. But if we 
lived in a world where it was all that easy, we’d all have cable modems, there would be 
no such thing as bottlenecks, and money would grow on trees (at least in my yard). 


Cable Modem Technology Overview 


Cable modem functionality requires a quick overview of the way CATV operates, and the 
means by which we get all those nifty, never-watched cable channels piped into our 
living rooms. 


CATV technology creates individual channels through the use of Frequency Division 
Multiplexing, or FDM, by dividing the available frequency spectrum of the well-shielded 
CATV coax cable into 6Mhz segments. These segments, more appropriately called 
channels, are used to transmit (broadcast) one-way information out to the attached 
nodes. Those nodes, connected in a branching tree (or tree and branch) topology, have 
certain tuners attached to them that allow them to focus on a particular 6Mhz channel 
and transmit the information they receive onto some medium (often a television). 


Cable Modem technology, then, utilizes a 6Mhz channel that has been reserved for 
receiving data; current downstream rates are either approximately 10Mbps or 36Mbps, 
depending on whether QAM64 is utilized as the transmission technology (advantage: 
higher throughput) or QPSK—Quaternary Phase Shift Keying—is utilized as the 
transmission technology (advantage: more robust, including Forward Error Correction). 
The return path utilizes a lower frequency range than the receive path and it is here 
where the technological concerns of the cable modem arise. The concerns are twofold: 
the shared cable wiring infrastructure and the traditionally one-way transmission 
direction. We'll take each in turn. 


Shared wiring infrastructure 


The concern with the fact that cable companies have a shared cable infrastructure 

stems, literally, from its tree and branch topology. Cable wiring, with regard to the 
transmission of one-way, downstream, identical signals that are used in everyday CATV 
viewing, is economical and appropriate for such uses. It allows for amplifiers to be 
placed along the cable path every once in a while to boost the signal to a necessary 
level in order to get the signal out to all the nodes. The problem this presents with regard 

to bursty data is that current cable modem technology will operate in localized . 

_ “branches” under a shared transmission medium design, in which a community of x 
number of users will share the same 6Mhz channel for getting their bandwidth. Figure 5- 
11 illustrates the tree and branch topology, then shows the isolated view of a certain 
“branch” amens which its nodes, or USETS, must share bandwidth. 
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Theoretical: 


To Cable 
Head-End 


Practical: 


Jo Cable 
Head-End 


= Shared Bandwidth Example 


=:Coax Cable run 


Figure 5-11: Tree and Branch Topology of CATV Wiring, and the Issue of Sharing 
Bandwidth Among Residences on a Certain Branch of the Cable Network. 


Is this really a valid concern? To a certain bandwidth utilization, the answer is no. The 
means of regulating access to the shared medium (in this case, the 6Mhz channel 
devoted to data) employed in many CATV systems is reportedly efficient, meaning that 
the 10Mbps (or 36Mbps) can be utilized even with many nodes transmitting near the 
maximum rate. 10Mbps is a lot of bandwidth for the home, unless you’re using it for lots 
of applications (movies, Internet access, and telecommuting) or there’s a hot new killer 
app out that requires lots of bandwidth and all your neighbors have it. Whether or not it’s 
a valid concern, having to share the bandwidth with the neighborhood isn’t too 
appealing; if your throughput depends on your neighbor not using their access too much, 
that could make your area a bad neighborhood. __ | 
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_ Another questionable issue regarding shared wiring has to do with how far up the trunk 
data must go in order to get to the head end (the place where this data is going to be 
redirected to wherever it’s going, like the Internet). The farther up the branch you go, the 
higher the number of users who must share the bandwidth. At some point the 

~ requirements will be too much and it is there where some sort of transmission medium, 
such as fiber, must be taken to get more bandwidth closer to the neighborhood. 


The last question to pose is: When has there ever been enough bandwidth, at any level 
of the network, for any amount of time? If you’ve ever had to suffer through waiting on 
the cable company to fix your line because you didn’t want to miss an episode of 
Friends, imagine if you had to endure that same wait for your mission-critical and career- 
critical corporate access. 


Traditional one-way transmissions 


To get the obvious out of the way: Cable is traditionally a unidirectional transmission and 
its infrastructure has been built around that premise. Also, cable head-ends are 

generally islands that exist as the products of one-way transmission mediums; in other 
words, they aren’t necessarily connected to other cable head-ends, making data 
exchange between and among them not immediately available and not intrinsic to their 
infrastructure. In contrast, every CO in the world is interconnected in one way or another, 
and prewired for bidirectional communications. This fact—that cable companies are 
traditionally downstream-centric or unidirectional—lends itself to other concerns. 


If we revisit the earlier diagram that outlines the tree and branch topology of the 
traditional CATV wiring infrastructure, this time looking a little closer at the means by 
which the content signal (the TV channel signal) is propagated down the tree and to all 
the branches, we see that the signal is boosted along the way by amplifiers. This fact 
starts to dig into the wallet issue surrounding cable operators and their ability to provide 
the hardware upgrades necessary for Residential Broadband over cable, as shown in 
Figure 5-12. | 


Notice that these amplifiers are pointing in the downstream direction. The implications of 
this fact are that cable operators, in order to provide residential broadband services, are 
going to need to replace those amplifiers with amplifiers that can send data both ways, 
or augment their downstream amplifiers with upstream amplifiers (much like | 
telecommunications COs will have to outfit themselves with ADSL modems). The 
difference is that the CO can outfit itself with enough ADSL modems (or ADSL line 
multiplexer capacity) to cover its subscribed users and add more modems/interfaces as 
demand merits. With cable amplifiers, proper amplifier additions must be added before 
even one downstream customer can subscribe to the service. Not an impossible task, 
just something that must be done; however, the economics of Internet users wanting 
more bandwidth are convincing and compelling reasons to complete such a task. 


A couple of other concerns many people share with regard to cable operating companies 
are network management and general market perception. Unfortunately, the perception 
of both is not positive. | 
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Figure 5-12: The Tree and Branch Topology, with the Amplifiers That Boost the 
Signal to Get It into the Neighborhoods. 


One thing that cable modems do have going for them, however, is content. The cable 
companies are the kings of content, and once residential broadband kicks in and 
bandwidth enough to get movies on demand, services on demand, all sorts of other data 
on demand, and pay-per-view prize fight equivalents is available, there will be few who 
can compete with the content delivery experience cable companies have. 
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WAN Technologies 


X.25 


The following is intended to familiarize you with WAN technologies and their | 
applications, fundamental behavior, and market implementations, It isn’t a full 
dissertation on any of the technologies, so if you’re interested in knowing facts such as 
which bit in the header of a Frame Relay PDU constitutes its candidacy for being 
dropped when the EBR for a given node is exceeded (the DE bit, for Discard Eligibility), 
you'll need to look elsewhere, because nat isn’t the intention here (it’s the second bit, 
after the flag). 


Entire books (such as the bookstore inhabitants mentioned earlier) can and are 
committed to the detailed treatments of each of the following WAN technologies; such 
detail doesn’t further the mission of this chapter, which is to familiarize you with remote 
access technologies (including WAN technologies) to the point of being conversationally 
familiar with them and enable you to understand them when you’re developing remote 
access applications. It’s context-based knowledge and the imparting of such knowledge 


is the overall goal of the WPRS, after all. 


We're starting this section with the genesis of WAN technologies, the beginnings of the 
WAN as a standardized means of providing wide area access for data networks. That 
first, old, widely deployed technology is X.25. i , 


lf you remember one thing about X.25, remember that it has intrinsic data integrity 
checks throughout its network “cloud,” the overhead of which introduces latency and 
makes X.25 less desirable for transmission between and among today’s powerful 


- desktop computers. If you remember two things about X.25, then also remember that it 


is not a standard for a public packet-switched network; it is a recommendation for 
interfacing with a public packet-switched network. 


-X.25 was created as a result of an ITU-T (the CCITT back then) study group charged 


with defining a standard interface recommendation for a public data network; to the © 
companies that needed such a service, it promised a means of avoiding the inhibiting 
proprietary network protocols in use at the time, provided by the likes of IBM (many 


different protocols from IBM), DEC, and others. It also meant a standard to which access 


devices for different vendors’ equipment could be manufactured, against which such 


~ devices could be tested for compliance, and by which different types of equipment, 


made by different manufacturers, could use a common carrier to send their data across 
wide distances. It was also a means by which such user-requested features such as 
Quality of Service could be implemented (QOS is an old technology for WAN _ 


technologies, but a relative newcomer to the realm of LANs). 


X.25 has been widely deployed and used over the years, both with public networks and 
private network implementations, because of its “abstraction” characteristics and 

because it generates a network cloud within which connections can be made with other 
devices that are connected to that cloud. The result is the creation of acommon and 
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~ centralized connection arena, or in more common terms, a public data network. The 


advantages of such a public network were two-fold and certainly economic: Rather than 
having to create a private network with expensive (and almost always grossly 
underutilized, though wholly paid for) leased lines running from each node to which 
connectivity was required (a mesh network), only one connection for each node was 
required. By creating a standard access protocol (okay, a recommendation), different 
types of computers, mainframes, or terminals could connect to the network and send 
their data; there was no need for separate networks for each type of device or each 
proprietary protocol. It put the means by which access was gained at arm’s length, and it 
allowed for a pooling of network resources, which in turn resulted in lower costs. 


Figure 5-13 outlines how a public data network, such as an X.25 network, can reduce 
the costs of access when many nodes require connectivity to many other nodes; or in 
simpler terms, the connectivity requirement of the network is many-to-many. 


The actual recommendation from the ITU-T (CCITT) came in 1974. It was since revised 
in 1976, 1978, 1980, 1984, and in its “Blue Book” recommendation of 1988, which is 


today’s most common implementation. 


Notice the term recommendation instead of the term standard. The ITU-T isn’t in the 
business of providing standards and instead provides recommendations, which the 
industry then promptly takes and calls a standard. Though it generally becomes a 
standard, the line of recommendation versus standards is clearly not crossed, for 


_ reasons such as endorsements, walking the middle-line...you get the idea. 


Though X.25 has.a lot of good qualities to it, among them its cost-effectiveness and wide 
availability, it does have limitations that are more a result of changing computing power 
and network architecture, as well as reduced tolerance of technology by today’s 
compelling applications, and less a result of problems with the technology itself. 


X.25 Technology Overview 


X.25 is a connection-oriented WAN technology, which means that “calls” are initiated, 
placed, and then dismantled as a matter of course for sending data from one node to the 
other, similar to our telephone network and dissimilar to today’s LAN technologies. In 
order for most PCs to interface with an X.25 network, a PAD (Packet | 
Assembler/Disassembler) is required. X.25 utilizes 128 or 256 byte packet sizes, which 
are too big to be good for voice and video applications and too small to be optimum for 
native data network formats. With the move toward multimedia content delivery and 
interaction over the network (which would include the WAN link, certainly), such limiting 


-factors—latency and less-than-ideal packet size—don't put X.25 in the very small 


pedestal that will hold the WAN technology of the future. 


As mentioned earlier, X.25 does a number of checks on any given packet as it passes 
through the X.25 network, which creates a delay (compared to networks that do very 
little checking of packet integrity, such as an Ethernet LAN) in the overall delivery of the 
packet. Simply put, the checks X.25 performs take time, and that time accumulates as 
the packet crosses an X.25 network. This factor is perhaps one of the most limiting 
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aspects of X.25 and will ultimately spell its demise in the face of other WAN 
technologies. There is a reason for this, however; when X.25 first came onto the scene, 
there was a need for such data integrity checks. 


Point-to-Point 


Branch } 


Branch 4 


Branch 2 


Branch 3 


Public (or private) Data Network 


Branch 1 Branch 5 


Branch 2 


Branch 3 


= WAN Router 


Figure 5-13: The Difference Between Using Leased Lines and a Public Data 
Network. 


X.25 was created when the devices utilizing its services were, compared to today’s 
standards, processor-poor. The requirements of the data network, in the time it was 
created and even revised, included a need to ensure the integrity of the data that 
crossed through its network cloud. That meant that checkpoints for data integrity at each 
stop (hop) along the network way had to be a part of the network, and when integrity 
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checks are done at the packet level, the requisite overhead and consequent latency is 
significant. Today’s computers, with their 300 million or so cycles per second, don't 
require such hand-holding transfers, because they have the computing horsepower to 
implement data integrity (error) checks and balances upon receipt of packets. If errors 
occur, the receiving computer simply lets the sending computer know of such errors 
(through NAKs) and requests the appropriate response, such as a retransmission. 


T-Carrier 


T-Carrier facilities have been around for over 30 years, and were designed as a means 
of digitizing and transmitting multiple voice channels over twisted pair media 
(multiplexing), increasing overall telephone network transmission capacity. 


AT1 line, by definition, is a digital transmission facility that provides 24 digitized | 
channels over two twisted pairs (a total of four wires). As time has gone on and T-Carrier 
services have been widely used, the differentiation between the widely used T-Carrier 

— facility and its throughput levels—transmission capability levels more accurately 
described with DSOs or DS1s—began to muddy. Today, many people intermingle the 
term T1 among carrier type and throughput capability, which tends to confuse the 
understanding of the technology. 


Thus, T-Carrier is a tricky bit of work, since its name is used to denote transmission 
signaling, throughput rates, and the carrier system itself. So if you say, “Il have T1 access 
to the Internet,” that could be interpreted to mean you have a dedicated 11 line that 
connects you to an ISP, and the equipment on either end creates one big 1.536Mbps 
pipe, or you have a Frame Relay connection to the Internet that runs over a T1 line, 
which operates at 1.536Mbps. Which do you mean? Either would be correct, though 
technically it would be more accurate (and descriptive) if the latter were to say, “I have a 
Frame Relay connection to the Internet. It’s running over a T1.” Does anyone wonder 
why T-Carrier technology can get a bit confusing? 


So to reiterate and conclude in one sentence: T-Carrier both defines the transmission 
medium (over copper) and is a defined transmission signaling technology es DSO 
channels of 64kbps each). 


T-Carrier Technology Overview © 


The T-Carrier facility is based on DSO (the 64kbps digital payload), which in this 
discussion will be called a channel. Note that the DSO is a digital transmission facility. 


A T1 is divided among 24 individual channels, each of which is generally used to support 
one telephone conversation, one analog modem connection to wherever, or one fax 
transmission coming in from your favorite office supply shop—the point being that a T1 
provides 24 virtual “telephone lines,” and what you do with them depends on how that T1 
is used. Through the use of compression, some applications of T1s can squeeze more 
voice channels out of one T1 line, but that application is in the PBX and voice end of 
things, not the remote access end of things. With remote access applications, you'll be 
getting 24 digitized 64kbps channels out of your T1. Because T1s are so prevalent, 
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the subject of T1s and how they work merits some more depth; see the section titled 
T1s, E1s, PRIs and All Those Bits. 


T-Carrier facilities use a signaling mechanism called Time Division Multiplexing, which is 
best explained by an analogy. Imagine you have a line of trucks taking payload to a 
destination in preordained, very specific intervals (precisely 8,000 times per second in 


this case, which is a pretty fast truck), and the trailer (open at the top in this example) 


has exactly 24 evenly spaced slots into which cargo can be placed. Now let’s say that 
you have 24 different companies that have reserved a spot—the same spot on each 
truck—within those 24 slots for the transport of their payload. When a truck starts moving 
out, it is loaded with its payload and heads across the T1 highway toward its destination. 
Thus, the 7th spot on the first truck’s trailer is occupied by payload from Company XYZ, 
as is the 7th spot on the second truck, the third truck, and so on, until Company XYZ 
hangs up its cargo contract and no longer wants to transmit its goods across the T1 
highway. The 7th spot on all the trucks then becomes available. We could call this the 
Channelized Trucking Company, since its trailers are all divided among 24 individual 
channels. 


A T1 behaves in a similar manner. Each of the 24 channels on a T1 has a specific 
payload capacity, which is equivalent to a DSO (or vice versa, meaning that a DSO is 
equivalent to the payload available on one channel of a T1—it’s kind of a chicken and 
egg deal), or 64,000 bits per second. 


This is all great and interesting if you’re putting together a rack of modems that need 
individual lines, but we’re in the WAN section, and we want one big pipe to the Internet, 
a specific remote location, or wherever; we don’t want it divided. How does that work? 
Well, let’s take a look at the Unchannelized Trucking Company to find out. 


Back to the line of trucks waiting to take payload to their destination across the T1 
highway. With the Channelized Trucking Company, each of its trucks had trailers that 
were divided into 24 separate slots, into which a company such as Company XYZ could 
place its payload of up to 64,000 bits per second. In contrast, the Unchannelized | 
Trucking Company has trucks with trailers that aren't divided into separate slots, and 
instead have the full 1.536Mbps of available payload to make available to one customer 
(for the reason why a T1 has a payload of 1.536Mbps instead of the generally stated 
1.544Mbps, see Technical Talk: T1s, E1s, PRIs and All Those se Figure 5-14 shows 
the difference between these trucking companies. 


As mentioned earlier, the T-Carrier facility i is based on its transmission of the DSO (the 
_ 64kbps digital payload) in increments of 24, which when aggregated into the T1 frame 
format becomes the basis of the entire North American Digital Hierarchy in the form of 
the DS1 (1.544Mbps). Figure 5-15 outlines the DS hierarchy and their corresponding 
voice channel capabilities. | | 
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Figure 5-14: The Channelized Trucking Company and Its Payload Division Versus 
the Unchannelized Trucking Company and Its One Big Payload. 
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Figure 5-15: The North American Digital Hierarchy and Its Corresponding 
Throughput Capabilities and Voice Channels. | : 


T2s are uncommon except in movie sequels. Generally, T1s are used until a throughput 
requirement somewhere around a T3 is required. 
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T1s, Eis, PRis and All Those Bits 


You've heard talk of T1 and E1, and you may have heard that they don’t have the same 
bandwidth capabilities and are not compatible, but you may be wondering: What's the 
difference, and why have two similar kinds, if not for entertainment/confusion value? 
Good questions, and a good subject for a Technical Talk. 


First we'll define the T1 in technical terms: A T1 consists of 24 DSO channels. Each DSO 
carries 64,000 bits of information per second, and with the addition of one control bit per 
T1 frame (the 198rd bit of a T1 frame), we get a total transmission rate of 1.544Mbps_ 
(1.536Mbps of which is available to the user). 


In the North American digital signal hierarchy, a DS1 (Digital Signal level 1) is equivalent 
to 24 DSOs (a T1), and the telecommunications infrastructure in North America is based 
on that hierarchy. (See Figure 5-15) Different parts of the world, however, have 
‘developed their own, different digital signal hierarchies. © 


In Europe, the European Hierarchy defines a DS1 as carrying 30 DSOs. In Japan, the. 
Japanese Hierarchy defines a DS1 as 24 DSOs, but defines a DS3 as 480 DSOs, versus 
the North American Hierarchy which defines a DS3 (T3) as 672 DSOs. Thus when there 
are discussions about T1s and E1s, and their differences in bandwidth and voice/data 
channel handling capabilities, the reasons for their incompatibilities and the need for 
different interfaces for each become clear. 


Back in North America, where T1s live in close quarters with ISDN PRI interfaces, the 
differences between the two require a closer look. The difference between the 
transmission characteristics of T1s and PRis are that (as we know) T1s utilize 24 DSOs 
and add a bit to the T1 frame for control, wnereas PRs utilize exactly 24 DSOs, but 
reserve the last (24th) DSO for the ISDN D Channel use. Figure 5-16 illustrates the 
difference. | 


T1 Frame = 


ISDN PRI Frame 


=DS0 (individual 64kbps channel) 


Figure 5-16: The Difference Between T1 Frames and PRI Frames. 
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Because the ISDN PRI utilizes one of the DSOs for its signaling, it doesn’t require the 
additional control bit to be added to each frame as T1s do. Thus, you may see bit (not 
big) differences between transmission rates of T1s (1.544Mbps) and ISDN PRIs 
(1.536Mbps), despite the fact that they both “utilize” 24 DSOs. 


ISDN PRI Technology 


ISDN PRI technology was discussed earlier in this chapter. We won’t beat it up again 
here in too much detail, though we will go over some (WAN-centric) concepts not 
covered earlier. 


As mentioned previously, ISDN has similar bandwidth capabilities as a T1, and uses the 
same 64kbit DSO as its basic building block. ISDN provides comprehensive 
administrative capabilities much better than a T1. The technical aspects of how it 
implements its administrative services are too involved (and provides definitions, not 
explanations). It can be loosely introduced by stating that ISDN has its own management 
“language,” which ISDN equipment (more accurately, ISDN Network Terminators, which 
are built into ISDN equipment) understands and can respond to, providing a native and 
inherent management structure within the technology itself. This is sometimes referred 
to, in ISDN and other technologies, as a management layer or a management “plane.” 
For those who want more technical information, and even more terminology, this 
management comes in the form of Q.931 messages and is carried within the LAPD 
frame. 


Like (one aspect of) T-Carrier, ISDN PRI is a signaling standard. Though ISDN isn’t the 
WAN technology or common carrier of the future, it has immediate, real-world 
applications today and is being implemented, more so recently, as increases in ISDN 
popularity have been making incremental appearances in the residence and office. 


Despite ISDN’s seemingly sputtered break into the WAN and the home, what can be 
attributed to ISDN’s success and track record is the use of control messaging (Q.931) 
and call setup/teardown (LAPD) for the WAN; both have been implemented in one form 
or another with stronger WAN candidates such as Frame Relay and ATM. 


‘For technical details on how ISDN PRI differs from T1s and even E1s, see the previous 
section titled 77s, E1s, PRIs and All Those Bits. | 


ISDN’s competition and implementations as a WAN technology are quite similar to 
T-Carrier. Though its future isn’t doomed by inadequate administrative facilities, other 
more attractive WAN technologies have more going for them than ISDN, and in 
comparison to the two following technologies, ISDN’s future is not destined for big 
things, but it’s certain to be around for some time to come. 
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Frame Relay 


Frame Relay could be called the modern makeover of X.25. Frame Relay came on to the 
WAN technology scene in the early 1990s, though standardization groups began work 
on it in the late 1980s, and has been growing in its installed base since its introduction to 
the market. There are a lot of things about Frame Relay that make sense, and it solves 
most of the problems other WAN technologies run into, including bursty traffic handling, 
administrative facilities, QOS capabilities, upper throughput range, latency (resulting 
from network “touching” of packets), wasted leased-line bandwidth and costs, and 
others. Is it the golden WAN technology? Some people would give you a very quick and 
resounding NO to that question, many would say it probably isn’t. | think it’s hard to say 
at this point, but Frame Relay has a lot of attractive characteristics, is placed in the 
overall telecommunications network scheme in such a way that allows the BISDN 
infrastructure to augment it, not replace it, and has throughput limits that seem to pone 
a lot of headroom. 3 


Frame Relay Technology Overview 


Like X.25, Frame Relay is a connection-based recommendation. A Frame Relay network 
is a public (or private, or some combination of the two) packet switching network, whose 
most appealing characteristic is that it does very little, in fact as little as possible, to the 
data that gets sent across its network. Instead, Frame Relay relies on end nodes to 
provide error correction, ACKs, NAKs, sequencing, and other processing-intensive 
operations. Frame Relay was designed to do as little as possible, and in so doing, keep 

latency across its networks to a minimum and the cost of its core network hardware to a 
minimum (cost savings which are passed on to the user). 


Similar to X.25, Frame Relay is an interface standard, and says nothing about the 
internal workings of the Frame Relay cloud. For end users, that’s fine: We don’t care 
what happens in the core network cloud, as long as we can get and send our data 
quickly, efficiently, cost effectively, and with lots of throughput. _ 


The most attractive aspects of Frame Relay include the following: 


¢ Frame Relay does very little to the data that passes through its network, which results 
in much lower latencies than X.25, though not as low as ATM. | 


e Frame Relay is based on a mesh network instead of a point-to-point network, which 
makes connection to a Frame Relay network much more economical than leased-line 
alternatives. 


e Since Frame Relay networks do less processing to their data, implementation of 
Frame Relay networks are more cost-effective than other, more processor-intensive 
WAN solutions. 

@ Frame Relay has the ability to move data at T3 (approximately eee rates and 
~ even slightly higher rates. 

e The maximum Frame Relay PDU is 4,096 bytes and is variable, allowing LAN frames 
to get Frame Relay headers prepended and then sent on their way (no slicing and 
o1ing of the original frame). 
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Frame Relay uses an economical approach to the transmission of data called Statistical 
Time Division Multiplexing (STDM). STDM is similar to the Channelized Truck Company 
discussed in the T-Carrier section (which used TDM), with a few important distinctions: 
The Frame Relay Company’s trucks don’t leave at preordained intervals and will carry 
any payload in their slots. Also, their trucks’ payload slots are not necessarily 


_ constrained to specific sizes. There is also a buffer near the loading dock that can store 


payload for a certain, small amount of time. If it helps (since Frame Relay often runs over 
T-Carrier), you can consider Frame Relay over T-Carrier in the following way: When 
Frame Relay is in charge, the Frame Relay Company takes over management of the 
loading dock and cargo-placing booms, and is more flexible with its payload and | 
scheduling requirements than the Channelized Truck Company. Though they may use 
the Channelized Truck Company’s trucks and trailers, they allow their customers’ 
varying-sized payloads to be dropped off with them, and then they (the Frame Relay 
Company) deal with stuffing those varying-sized payloads into the compartmentalized 
trucks of the Channelized Truck Company, and also deal with unloading ten0 punting 


back together) when the trucks reach their destination. 


Frame Relay works on the basis of Committed Information Rates, Committed Burst 
Rates and Excess Burst Rates (CIR, CBR and EBR respectively). That means that 
bursty networks such as LANs can get Frame Relay service at a certain CIR and exceed 
that rate during bursty periods up to the CBR or EBR (extended periods at or above EBR 
will make your data eligible for being dropped) without having to waste financial 
resources on leased lines that equate to the EBR. For example, you might have a 
512kbps Frame Relay CIR that’s been brought to your premises via 11; if your 
corporation at times exceeds 512kbps, perhaps up to 1Mbps under certain conditions, 
the Frame Relay interface will handle that excessive data. If your EBR were 1Mbs and | 
you had bursts that were hitting 1.2Mbps, then 1.2Mbps would be eligible for being 
dropped within the Frame Relay network. The advantage of Frame Relay’s ability to 
handle bursty traffic, in this situation, is that you don’t have to lease an expensive T1 line 
to get burst rates of 1Mbps or 1.2Mbps; if your sustained average throughput is 
512kbps, you can base your usage on that rate, not on your peak, or burst, rate. There 
are other, more sophisticated means of provisioning peak rates in Frame Relay, which 
have to do with buckets and credits, but the details of such algorithms are outside the 
scope of this discussion. 


ATM stands for Asynchronous Transfer Mode, and has been positioned as the 
underlying technology to take networking—both data networking, video transmission, 
and telecommunications—through the 21st century, all on the same wire. And if the 
amount of planning, theorizing, debating, refining, and general thought that has gone 

into ATM is any representation of its chances of pealevind that lofty intention, then ATM's 
chances are good. 


ATM, however, can be intimidating, often because of the sheer volume of dry reading or 
research that must be done to achieve even a reasonable familiarity. The result, too 
often, is a break after only sipping on its details, from which many never return. 
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This treatment of ATM is an intentional departure: It’s been structured to explain why 
ATM is the way it is, and by doing so should let you get through it with the least amount 
of pain or sleepiness. 


- Getting to ATM 


We’ve gone through technical overviews of other prominent WAN technologies already, 
and we’ve seen a sort of trend. X.25 brought the cost-effectiveness of standardization 
and shared mesh topologies to data networks; T-Carrier utilized a digital 
telecommunications infrastructure, and the well understood T-Carrier technology, to get 
data moved from point to point using the existing and ubiquitous PSTN. Frame Relay 
improved on both, taking the attractive shared network packet-switching attributes of 
X.25 and the low-latency attributes of T-Carrier, and then threw in its own added features 
to make it a great solution as a shared mesh data network for today’s high-speed client 
computing. And in the beginning, the middle, and still today, there was the need to 
transmit plain old voice data throughout the world. | 


We also found that there is another network sending out data of one sort or the other, 
which is the CATV network. It utilizes its own means of moving data, whether that’s 
movies, digital music, or 24 hours of television shopping, which implements none of the 
transmission technologies discussed above. 


But there has been something missing throughout all of this; a fundamental 
cohesiveness that all these WAN solutions and voice transmission facilities lack. What's 
missing is a common network, certainly, but also a common carrier, which is the aim of 
ATM. ATM strives to be a common carrier for voice, data, audio, video, and any other 
data that can be transmitted over one network that would become the Information 
Superhighway. You name it, and ATM wants to be able to send it, and nde been 
designed to be able to do just that. 7 


Creating the Common Carrier’s Shopping List 


In order to be the common carrier of data, voice, video, and any other type of data, ATM 
must provide all of the services each of the data Bypee" need, but must do so within the 
constraints of one data type. 


The difficulty with trying to please all of the people (or data types) all of the time centers 
on the fact that different data types are best serviced at different sized PDUs. Voice is 
best served by small packet sizes, such as 32 bytes per PDU, while “computer” data is 
served best my much larger sized PDUs (Frame Relay, a data-centric technology, has a 
maximum PDU of 4,096 bytes). Thus, there is a disparity between voice and data. How 
do you solve these differences? First, you must be very fast; so fast that the 
compromised (smaller or larger than you would like) size of the PDU is grossly 
outweighed by the increase in speed or throughput. Second, you must promise and 
deliver compelling reasons—real world reasons—why changing from the status quo is 
worth it in the short term, the near future, and the long run. 
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The means of dealing with the difference in optimum PDU size is: being fast and being 
everywhere. That brings us back to the “one data type for all” philosophy. Why one data 
type? Because one data type, with a fixed length and fixed header sizes, would enable 
that same data type (regardless of its content) to traverse the network quickly, efficiently, 
and in hordes and hordes, gigabits and terabits at a time. It is so efficient to use fixed 
sized PDUs that the switches that forward them can actually function and process at 
rates higher than the line speeds themselves. That’s fast switching. Even if you have to 
chop up larger PDUs from their native format (like Ethernet with its 1518 byte maximum | 
PDU) into smaller PDUs to utilize the network, the benefits of the anticipated cost 
effective and higher bandwidth WAN service availability and low latency associated with 
the smaller PDU implementation make the work involved in chopping up the data (and 
reassembling at the other end, if necessary) worth the effort. 


The means of providing compelling reasons for changing from the status quo are 
somewhat less immediately tangible, but certainly are at least as important as all the 
technical reasons combined. In the short term, the common carrier can actually 
concentrate on a subset of its strengths: the ability to move data in large volumes. One 
short term use might be upgrading existing LAN backbones to the higher capacity 
capabilities of a common carrier technology. A mid-range or near-future reason for 
utilizing the benefits of a common carrier might be to augment the “coming of age” of 
multimedia applications to the desktop. This movement requires a significant amount of 
bandwidth, and also a means of guaranteeing a certain level of service (voice and video 
over data networks exist today, with Internet phones and monitor-top desktop cams, but 
they’re jittery and hog all of the available bandwidth, and generally speaking, at best are 
novelties rather than real solutions). For the long term, compelling reasons for a common 
carrier include all of the preceding reasons, as well as the ability to turn multiple 
information service networks into one cohesive delivery platform. This is one compelling 
reason to move to a common carrier; if you could take advantage of using one network 
even for data and voice (and thus make it more cost effective in terms of service 
charges, administration, application and content development, and new market 
potentials), concessions would be made to integrate those services. 


When we put these requirements of a common carrier into shopping-list form, the end 


result, much more concisely presented, looks something like the following: 


e Carry all sorts of different data, including voice, “computer” data, video, and others. 


e When carrying that data, allow users to request various levels of “service” so that 
information delivery that is sensitive to delay, bandwidth, constraints, or timely 
sequential arrival can be accommodated. 


e Carry the data in large volumes, quickly, and efficiently. In specific terms, provide for 
lots of bandwidth, low latency, and make sure switching infrastructure processing 
power (“inside-the-network-cloud” equipment efficiency) isn’t prohibitively expensive. 


e Be media-independent, allowing existing transmission facilities (copper, fiber, or co- 


ax) to migrate without making expensive physical changes to their infrastructure. 


° Create the ability to merge all the various information networks, including voice, data, 
- video, into one network. 7 
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e in merging those networks, allow graceful handling of different transmission 
characteristics, such as bursty transmissions (variable bit rate) versus continuous 
_ transmissions (constant bit rate). 


e Allow for an incremental migration from other technologies; avoid the requirement of 
an “all or nothing” approach. 


e Be designed in such a way that limits the likelihood of being outdated in the near — 
future. Don’t be an interim solution, be the long term solution. 


We can boil these requirements down even further if we try to: 


_ @ Carry all information data types efficiently and meet the different transport 
requirements of each. 


e Be available over any transport media and provide mechanisms to interact with 
existing technologies. 


e Be the transmission technology for the long term future of information delivery. 


One issue that was alluded to but not directly addressed comes last. We have worldwide | 
PSTN interconnectivity, which means you can call someone across the globe just as 
easily as you can call your neighbor across the street. Being the common carrier of the 
future of information delivery necessitates that information boundaries, in a world where - 
the economy is global rather than local, be non-existent. It further requires that such 

~ technology not be implemented in one way in North America, another way in Europe, 
and another way in Japan and Asia. This brings us to the last item on the common 
carrier shopping list: 


e The common carrier must be a worldwide standard. 


ATM Technology Overview 


With all those shopping list items, you can imagine the difficulty coming up with a 
technology that met all the requirements. Perhaps an even more challenging task would 
be choosing among the different ideas and methods, often heatedly defended and 
promoted, for going about achieving such a standard. An international body comprised 
of industry leaders in both the telecommunications and data industries, those who 
(choose the word as you will) created, devised, invented, or standardized ATM, have 
done it. The means by which ATM reaches those lofty goals is the & subject of the 
following sections. 


Carrying all data iyoes 

_The means by which ATM carries all data types in an efficient, fast- -switching, low- 
latency means is by having a standard sized ATM PDU, called a cell, of 53 bytes. 
Hereafter, the ATM PDU will be referred to as a cell, much like an Ethernet frame is 
often referred to as a packet. 


72 


Volume 4 Remote Access Services | 


The ATM Cell. An ATM cell is always 53 bytes. An ATM cell always has a 5-byte 
header, leaving a 48-byte payload. Always. This presents a deterministic, or specific and 
predictable, means of determining the beginning and end of an ATM cell, which in turn 
makes equipment that must handle ATM cells efficiently and quickly. The handling of all 
data types, including voice, data, and video, is thus done within the 53-byte cell. ATM 
transmission characteristics (Such as service requirements, routing information, source 
and destination addresses, path identifiers, and payload type identifiers) are carried in 
the 5 byte ATM header. The information (the actual “data” that’s being transmitted), plus 
that data’s information necessary for its adaptation to ATM, is handled in the 48-byte 
payload. That is the crux of ATM. All other features, services, capabilities, and 
characteristics must do their work within those confines. Figure 5-17 puts this into a 
picture. 


ATM Cell 


48 byte Payload: 5 byte ATM Header: 
Carries data payload, as well as Provides cell information such as service 
necessary LAN frame headers and AAL requirements, routing information, source and 
_ information used to reconstruct the LAN | - destination addresses, and payload content. 


frame upon arrival at LAN destination. 


Figure 5-17: The ATM Cell, with the Division of Carried Information Between the 
Header and the User-Available Payload. 


ATM Connections. Pick up the telephone, dial your friend’s number, and you’ve 
completed a call. You have a number identifier (the telephone number), and within the 
telecommunications network you have a circuit assigned to your call, which is sent over 
larger, multi-circuit transmission facilities (multiplexed). Though ATM connections don’t 


_ fit exactly into that example, they’re similar. ATM connectivity works on the basis of two 


identification elements: the Virtual Channel Identifier (VCI) and the Virtual Path Identifier 
(VPI). Combined, these two channel elements constitute the Virtual Circuit Identifier. 


Perhaps a better comparison is a TCP/IP address: In the TCP/IP network address 
210.21.98.3 with a subnet mask of 255.255.255.0, you have the network address 


(210.21.98) and the local address (3) which together constitutes the IP address. Network 


address + local address = IP address. In ATM terms, VCI + VPI = Virtual Circuit 
Identifier. Both the IP address (in IP networks) and the Virtual Circuit Identifier (in ATM 
HEIWOIKS) are used for routing their respective PDUs across their networks. 
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The reason the telephone example is pertinent, though, is the virtue of its connection- 
oriented sequence. With the telephone call, the circuit is created when necessary (when 
the person picks up the telephone and dials the number) and torn down when they hang 
up. ATM works in a similar manner, though its general usage provision differs slightly. — 
Switched Virtual Channels, or SVCs, are similar to telephone calls in that they are 
created when the user requests use of the network (in computer terms, your “request” 

_ might be an attempt to connect to a server on the other side of an ATM WAN link, at 
which time the connection would likely be initiated and made so quickly that it appears 
as though the connection were always “up”). In contrast to the need to initiate a call to 
establish the connection, Permanent Virtual Circuits, or PVCs, are always up. Examples 
of an SVC and a PVC, respectively, would be a dial-up connection to the Internet and a 
dedicated connection; with a dial-up connection you must tell your modem to dial your 
ISP, at which time a connection is made. An example of a dedicated connection to the 

_ Internet would be an ISDN connection that’s on 24 hours a day, always connected and 
ready for transferring data to or from the Internet, whether any data is paseiid back and 
forth or not. 


Adaptation to ATM. To be the carrier of all data types, all data types must be 
convertible into ATM cells. This conversion, or adaptation, is done through the ATM 
Adaptation Layer (AAL). With this abstraction of ATM, or in less technical terms, by 
outsourcing the means by which other technologies (or data types) become compatible 
with ATM, the technology makes itself available to any type of data. pPiguie 5-18 
illustrates this. 


~Because some data-type technologies have additional information necessary to provide 
adaptation to ATM, part of the 48-byte payload may be dedicated to the adaptation of a 
given data type. Such data types have been specified and standardized within ATM 
technology. Figure 5-19 illustrates those AAL types. 


Although the ATM cell facilitates one size for all sorts of different data types, and the 
AAL allows those different data types to be adapted to ATM cells, neither inherently 
solves the issues surrounding different data types’ dissimilar service requirements. LAN 
data is traditionally bursty; voice traffic is traditionally a constant state. Video is sensitive 
to timing requirements. ATM addresses these issues through traffic classification. 


Classification of ATM Traffic. The classes of traffic within ATM have been categorized, 


_ recategorized, uncategorized, and then rethought and represented. Throughout all the 


changes of classification naming and conventions the fundamental requirements have 
remained the same. Those requirements deal with which service parameters the traffic 
being adapted by the AAL is most sensitive to. They fall into a few categories: 

e Constant bit rate requirements. | 

e Variable bit rate requirements, which are sensitive to timing constraints. 


-@ Connection-oriented variable bit rate requirements, such as bursty pea 
applications. 


e Variable bit rate requirements, such as bursty computer- -data ane Frame Relay WAN 
applications. 
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Adaptation of LAN data to ATM. 


LAN Frame 


§ byte ATM Header 


Provides cell information such as service 


4b te AAL ‘header’: requirements, routing information, source and 
Carries necessary AAL information destination addresses, and payload content. 


used to reconstruct the LAN frame 
upon arrival at LAN destination. 


P * Note that many uses of AAL Type 3/4 are being moved to Type 5, 
44 byte Payload: which has lower overhead than Type 3/4; Type 5 uses less bytes 


Carries LAN data payload to transmit overhead information than the 4-byte ‘AAL header’ 
, seen here in Type 3/4. 


Adaptation of Voice to ATM 


Voice data 


48 byte Payload: _ & byte ATM Header: 
Carries Voice data. | Provides cell information such as service 


requirements, routing information, source and 
destination addresses, and payload content. 


Figure 5-18: The ATM Adaptation Layer. 
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AIM Adaptation Layer Types 


Type Usage Summa Data Bytes (of 48-byte ATM payload 


minimal sequencing or error detection (contrast to Type 
3/4). Used in support of upper protocol (such as Frame 
Relay) transmission over ATM. 


* Type 3/4 and Type 5 currently garner the most interest. Types 1 and 2 were initial (and not widely used) definitions. - 


Figure 5-19: ATM Adaptation Layer Types. 


These classifications were grouped into Types, such that there were Type 1, Type 2, 
Type 3/4 (Types 3 and 4 were combined), and Type 5 standards established for 
adapting different data types to ATM. Each different type has a specific means by which 
data is placed into an ATM cell's payload. For a technical example, a Type 1 PDU starts 
with a 4-bit sequence number (placed at the beginning of the payload part of the cell), 
then has a second 4-bit sequence dedicated to providing error correction to the first 4-bit 
sequence, then has an optional 8-bit (one byte) pointer field (its use or nonuse identified 
within the initial 4-bit sequence field), leaving the 46 or 47 bytes available for actual data. 
Why the technical example? The importance of the example is that a Type 5 does not 
have the same 4-bit, 4-bit, then optional 8-bit fields in its payload field; these types 
specify how data is segment and “formatted” into an ATM cell, in order to best 
accommodate different data types individual service needs. 7 


Thus, while ATM has a standard 5-byte header and 48-byte payload, the format of the 
payload differs among different AAL “Types.” Yes, my nose is getting a little fizzy too. 
But such classification of types for ATM allows switches to make very quick decisions 
regarding the servicing of a cell based on its type, which contributes to and facilitates the 
overall ability of ATM to provide the appropriate quality of service to many different types 
of data, all within the same transport technology, or to keep with our terminology, allows 
ATM to become the common carrier. 


Whew. So all these attributes of ATM—the size of the cell, its means of connection to 
other ATM equipment, the adaptation of different data types to ATM formats, and the 
classification of ATM traffic—all contribute to (or facilitate, depending on your — 
perspective) ATM’s ability to carry all data types. 


Media independence 


Media independence is achieved with ATM because its standard does not require that a 
certain medium be employed. It is media independent, much like you can buy a | 
Windows NT machine and put an Ethernet, Token Ring, or FDDI card in it and still 
~achieve network capabilities. Thus a manufacturer, if it so chooses, could implement 
_ATM over standard CAT 5 UTP networking cable (found all over the place in Ethernet 
LANs today). Or a manufacturer could implement ATM over multimode fiber, utilizing the 
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high transmission rate traits of fiber and the fast switching capabilities of ATM to create a 
backbone that speeds all sorts of data over a backbone. Or a manufacturer could 
implement ATM over microwave transmission facilities. | 


Of course, there is engineering to be done to figure out how to get, say, CAT 5 UTP to 
transmit the electrical signals that will carry the signal on which ATM will be transmitted. 
With Windows NT, you cannot simply touch a network wire to the outside of the box and 
expect to get connectivity; you must have an interface card, engineered and designed 
for a certain medium such as Ethernet, installed and configured to run with Windows NT 
in order for network connectivity to be achieved. ATM’s requirements, whether 


~ implementing it on Windows NT, a Cisco router, or in a Northern Telecom 


telecommunications switch, are similar. 


To ensure interoperability among different vendors’ products, there are guidelines 
created to provide an understood playing field for different media implementations. 
Standards exist today for the transmission of ATM over certain media including CAT 5 
UTP, T1, E1, T3, E3 and fiber, to name many. 


The long-term carrier 


ATM’s design to send all known data types is augmented with its abstracted 
transmission model, which allows the unknown data types of the future to fit into its 
model, or to be fit into its model, without having to rewrite the technology’s infrastructure. 
This, of course, is due to the planning and future-minded engineering that went 

into ATM. | 


Another requirement for the common carrier of the future centers around its need to be 

relatively light in terms of processing requirements, which is a reflection of the evolution 
of the client computer. As mentioned in the X.25 and Frame Relay technology sections, 
the computer that sits on today’s desktop is far and away more powerful than those that 
sat on desktops 10 or 20 years ago. In fact, it’s more powerful than the mainframes that 


were servicing the terminals that were sitting on desktops 10 or 20 years ago. As a 


result, the processing burden for ensuring the integrity of data transmissions can be 
placed on the end unit, not the core network switch. For the “computer” data part of 
ATM’s long-term common carrier candidacy, that means that ATM's hands-off approach 
to sending data (ATM doesn’t do significant, and therefore processor- and latency- 
intensive, error checking on its cells as they move through the network) situates it well 
for long-term viability. There are other data types to be concerned with, though, such as 
voice. 


Another advantage of the continuous leapfrogging in processor power and technology is 
that its benefits, in the ability to move tons of data, are also reaped in switches. That 
means that any data being sent over an ATM switch (not just “computer” data) is 
benefiting from process speed improvements. More than the quality of service available 


for voice, this fact becomes pertinent because of ATM’s ability to handle lots of data 


without introducing latencies, which any common carrier that will serve information. 
transmissions for the long term must certainly be able to do. Handle lots of data and 
handle it quickly, which brings us to video. 
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Video is inherently bandwidth hungry. It also has many QOS requirements, such as a 
constant bit transmission rate that the network can guarantee for the duration of the 
connection, which puts additional processor (and logic) burdens on the network, while 
ensuring very little loss. In order for a common carrier to be viable for video and 
multimedia transmission applications, it must have the ability to provide a guaranteed 
QOS so that video or audio is smooth and constant, not jittery and intermittent due to 
dropped or delayed cells. With the combination of video and data networks, the issue of 
QOS is equally important, indeed perhaps more important, for mission-critical 
applications as well. When bandwidth-hungry multimedia applications are utilizing 
perhaps disproportionate network resources, it is vital that mission-critical applications 
not be starved of bandwidth, latency, or other QOS requirements. ATM has the 
mechanisms built into it to facilitate all of those requirements. 


Another requirement of the long-term common carrier technology that will prevail is that it 
must have administrative facilities. The need to be able to get administrative information 
from the common carrier of the future is a must, and ATM is well situated in that category 
as well. 
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CHAPTER 6 


RAS Programming Guide 


Remote Access Service (RAS) provides remote access capabilities to client applications 
on computers using Microsoft® Windows® operating systems. RAS client applications 
can perform the following tasks: 


ie Display any of the RAS common dialog boxes. This includes the main Dial-Up 
Networking dialog box, the Dial-Up Networking Monitor property sheet, and other 
dialog boxes for creating, editing, copying, or dialing a phone-book entry. 


e Start and end a RAS connection operation using the common dialog boxes or the low- 
level dialing functions. 


© Create, edit, or copy phone-book entries using the common dialog boxes or the low- 
~ level phone-book functions. 


e Work with entries in the RAS AutoDial mapping database. This database maps 
network addresses to the phone-book entry that can establish a connection to the 
address. 


e Get RAS information, including information about existing RAS connections, 
information about the RAS-capable devices configured on the local computer, and 
notifications when a RAS connection begins or ends. 


Microsoft® Windows NT® version 4.0 also provides support for RAS server 
administration and for third-party extensions to RAS server security and connection 
management. Windows® 95 does not provide RAS server support. 


RAS Common Dialog Boxes 


- Windows NT 4.0 provides a set of functions that display the RAS dialog boxes provided 
by the system. These functions make it easy for applications to display a familiar user 
interface so that users can perform RAS tasks. For example, users can establish and 
monitor connections, or work with phone-book entries. Windows 95 does not currently 
support these functions. | : 


The RasPhonebookDlg function displays the main Dial-Up Networking dialog box. 
From this dialog box, the user can dial, edit, or delete a selected phone-book entry, 
create a new phone-book entry, or specify user preferences. The RasPhonebookDlg 
function uses the RASPBDLG structure to specify additional input and output 
parameters. For example, you can set members of the structure to control the position of 
the dialog box on the screen. You can use the RASPBDLG structure to specify a 
RasPBDligFunc callback function that receives notifications of user activity while the 
dialog box is open. For example, RAS calls your RasPBDlIgFunc function if the user 
dials, edits, creates, or deletes a phone-book entry. 
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You can use the RasDialDlg function to start a RAS connection operation without 
displaying the main Dial-Up Networking dialog box. With RasDialDig, you specify a 
phone number or phone-book entry to call. The function displays a stream of dialog 
boxes that indicate the state of the connection operation. The RasDialDlg function uses 
a RASDIALDLG structure to specify additional input and output parameters, such as - 
position of the dialog box and the phone-book subentry to call. 


To display the Dial-Up Networking Monitor property sheet, call the RasMonitorDlig 
function. This dialog box enables the user to monitor the status of existing connections. 
The RasMonitorDlg function uses a RASMONITORDLG structure to specify additional 
input and output parameters, such as the position of the dialog box and the property 
sheet page to display on top. 


You can call the RasEntryDlg function to display a property sheet for creating, editing, 
or copying a phone-book entry. The RasEntryDlg function uses a RASENTRYDLG 
structure to specify additional input and output parameters, such as the position of the 
dialog box and the type of phone book operation. 


RAS Connection Operations 


Windows NT 4.0 and later versions provide the RasPhonebookDlg and RasDialDig 


functions that display the built-in user interface for starting a RAS connection operation. 


For most applications, this is the preferred way to start a RAS connection operation. 
Windows 95 does not currently support these functions. 


The remainder of this section describes the low-level functions for starting a RAS 
connection. These functions are available on both Windows NT 4.0 (and later versions), . 
and Windows 95. 


A RAS client application uses the RasDial function to establish a connection to a RAS 
server. The RasDial function starts the connection operation, which is then carried out 
by the Remote Access Connection Manager. 7 


The Remote Access Connection Manager is a service that handles the details of 
establishing the connection to the remote server. This service also provides the client 
with status information during the connection operation. The Remote Access Connection 


_ Manager starts automatically when an application loads the RASAPI32.DLL. 


The RasDial call specifies the following information when it starts a connection 
operation: 


e The connection information that the Remote Access Connection Manager needs to 
establish the connection. 


e An optional notification handler that receives progress notifications during the 
connection operation. If the RasDial call specifies a notification handler, the call is 
asynchronous; otherwise, it is synchronous. 
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e An optional RASDIALEXTENSIONS structure to enable or disable extensions to the 
RasDial operation. The extensions permit a RAS client to directly enable some | 
modem settings, to control whether RAS uses the prefixes and suffixes in a phone- 
book entry, and to support paused states during the connection operation. 


Synchronous Operations 


When RasDial is invoked as a synchronous operation, the function does not return until 
the connection has been established or an error occurs. Synchronous mode provides a 
simple way for a RAS client to establish a connection. The client can simply call 
RasDial, wait for the function to return, and then call the RasGetConnectStatus 
function to determine whether the connection operation was successful. Once the 
connection has been established, the client application can terminate without breaking 
the connection. If an error occurs, the client application must shut down the connection 
operation before terminating. 


The disadvantage of synchronous mode is that the client does not receive progress 

~ notifications as the connection operation proceeds. As a workaround for this lack of 
progress notifications, a synchronous mode client can use a separate thread that calls 
RasGetConnectStatus to poll for and display the current state. However, for RAS 
clients that want to receive progress information, ie preferred technique is to invoke 
RasDial asynchronously. 


Asynchronous Operations 


~ When RasDial is invoked as an asynchronous operation, the function returns 
immediately. In asynchronous mode, the RasDial call must specify a notification handler 
that the Remote Access Connection Manager uses to inform the client whenever the 
connection operation changes states or an error occurs. 


The notification handler can be a window to receive messages, or a RasDialFunc, 
RasDialFunc1, or RasDialFunc2 callback function. The Remote Access Connection 
Manager makes its asynchronous notifications in the context of the thread that made the 
RasDial call. For this reason, the calling thread must not terminate until the connection 
operation has been successfully established or an error occurs. As in synchronous 
mode, the client application can safely terminate once the connection has been 
established, and it must shut down the connection operation if an error occurs. 


Phone-Book Files and Connection Information 


A RasDial call must specify the information that the Remote Access Connection 
Manager needs to establish the connection. Typically, the RasDial call provides the 
connection information by specifying a phone-book entry. The connection information in 
a phone-book entry includes phone numbers, bps rates, user authentication information, 
and other connection information. 
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A RAS client uses the parameters of the RasDial function to specify a phone-book file 
and an entry in that file. The /oszPhonebookPath parameter can specify the name of a 
phone-book file, or it can be NULL to indicate that the default phone-book file should be 
used. The /oRasDialParams parameter points to a RASDIALPARAMS structure that | 
specifies the name of the phone-book entry to use. 


To display a list of phone-book entries from which the user can select a connection, a 
RAS client can call the RasEnumEntries function to enumerate the entries in a phone- 
book file. 


To make a connection without using a phone-book entry, the RasDial call can specify an 
empty string for the szEntryName member of the RASDIALPARAMS structure. The 
RASDIALPARAMS.szPhoneNumber member must contain the number to call. In this 
case, the Remote Access Connection Manager uses the first available modem port and 
default values for all other settings. 


User Authentication Information 


The Remote Access Connection Manager service on the client computer sends a user 
name and password to the RAS server on the remote computer. Before it will establish a 
connection, the remote server uses this information to authenticate the user. By default, 
the Remote Access Connection Manager sends the user name and password of the 
currently logged-on user. The RAS client can use the RASDIALPARAMS structure 


_ specified in the RasDial call to specify a different user name and password. 


If the remote server cannot authenticate the user with the specified information, it can 


allow the connection operation to enter a paused state to enable the RAS client to collect 


different authentication data from the user. 


Other Connection Information 


The members of the RASDIALPARAMS structure can 1 also specify the following 
connection information: 
e A phone number to override the number in the phone-book entry. 


e Acallback phone number that the remote server can call back to establish the 
connection. 


e The name of the remote network domain on which the authentication is to occur. 


For the callback number and the domain, the RASDIALPARAMS members can either 
indicate that RAS should use the information in the phone-book entry, or it can provide 
information that overrides the phone-book data. 


_ARAS client can use the loRasDialExtensions parameter of the RasDial function to 


control whether RAS uses a phone number prefix or suffix specified in a phone-book 
entry. 
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Connection States | 

During the process of connecting to a remote server, the Remote Access Connection 
Manager and the RAS server on the remote computer perform several steps to establish 
the connection. Each of these steps is identified by a connection state. The 
RASCONNSTATE enumeration is a set of values that correspond to these connection 
states. The connection states can be divided into the following three groups: 


Running states 
The running states are the parts of the connection operation that RAS handles 
automatically, such as connecting to the necessary devices, authenticating the user, 
and waiting for a callback from the remote server. Unless an error occurs, the RAS 
client need take no action other than to pass the notification on to the user. 


Paused states 
The paused states occur when the remote server pauses the connection operation to 
get additional input from the user. During a paused state, the user can type a callback 
number, a different user name and password if the user autnentieaion fails, or a new 
password if the old one has expired. 
— Terminal states : 

The terminal states occur when the connection has been successfully established, the 
connection operation has failed, or the connection has been broken by a RasHangUp 
call. : 


_ There are several mechanisms that a RAS client can use to determine the current state 
of a connection operation. When a RAS client executes the RasDial function 
asynchronously, the Remote Access Connection Manager sends progress notifications 
to the client’s notification handler whenever the connection state changes. In addition, 
the client can use the RasGetConnectStatus function to get the current state o any 
RAS connection operation. 


Notification Handlers 


An asynchronous RasDial call must specify a notification handler. During an 
asynchronous connection operation, the Remote Access Connection Manager uses the 
notification handler to inform the RAS client whenever the connection state changes or 
an error occurs. 


The actions performed by a notification handler can be divided into the following 
categories: 
e Handling errors. 


e Providing feedback to the user as the connection operation proceeds through the 
various connection states. See Informational motneations: 


e Handling paused states. 


_ @ Signaling the RAS client application when the connection operation has been 
ee see competion Notifications. 
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There are three types of notification handlers, each of which receives the same basic 
information: the current connection state and an error code that is nonzero only if an 
error has occurred. 


Value Definition 


RasDialFunc — A callback function prototype that receives only the current 
connection state and error code information. 


RasDialFunct A callback function prototype that receives the HRASCONN 
connection handle and extended error information in addition to the 
basic information. The connection handle parameter makes 
RasDialFunci1 useful for client applications that support multiple — 
simultaneous connection operations. This allows the client.to specify 
the same callback function for all operations, and enables the 
callback function to determine which connection is changing states. 


-RasDialFunc2 A callback function similar to RasDialFunc1. However, 


RasDialFunc2 is enhanced to support multilink connections. 


Window handle A window handle to which RAS sends WM_RASDIALEVENT 
| messages containing the current connection state and error code 
information. Use this method if your source code must be compatible 
with 16-bit Windows, because 16-bit Windows does not ounP et, 
either of the callback functions. 


The Remote Access Connection Manager suspends the connection operation until the 
notification handler returns. For this reason, the handler should return as soon as 
possible unless an error has occurred. 


The RasDial function should not be called from within a notification handler. The other 
remote access functions (RasGetConnectStatus, RasEnumEntries, 
RasEnumConnections, RasGetErrorString, and RasHangUp) can 1 be called from 
within a handler. 


oe RAS Errors 


When an error occurs, the Remote Access Connection Manager invokes the client’s 
notification handler. The notification indicates the connection state when the error 
occurred, and a code that identifies the error. In these cases, the notification handler 
should call RasHangUp to end the RAS connection. 


The RAS client can use the RasGetErrorString function to get a display string 
describing the error. 
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Informational Notifications 


For the connection states known as running states, no action is required of the 
notification handler unless an error occurs. Running states occur during the parts of the 
connection operation that RAS handles automatically, such as connecting to the 
necessary devices, authenticating the user, and waiting for a callback from the remote 
server. The notification is simply a progress report to the client. 


The client can choose to pass these informational notifications on to the user. In some 
running states, the client may want to display additional information. For example, a 
notification handler that receives a RASCS_ConnectDevice notification can call the 
RasGetConnectStatus function to get the name and type of the device being connected 
to. Another example is when the client receives a RASCS_ Projected notification. This 
occurs when the RAS projection phase of the connection operation has been completed. 

_ The client can call the RasGetProjectionInfo function to get additional information about 
the projection. The client can use this information to notify the user as to which network 
protocols can be used by this connection. 


You should avoid writing code that depends on the order or occurrence of particular 
informational states, because this may vary between platforms. 


Completion Notifications 


The Remote Access Connection Manager continues progress notifications until the 
connection operation has been completed. This occurs in the following situations: 


e The handler receives a RASCS_Connected, or RASCS_ Disconnected notification. 
The RAS client application can exit without breaking any established connection. 


e An error occurs. The handler receives a notification indicating the error and the 
connection state when the error occurred. The RAS client application can exit. 


The RAS client application should not assume the connection operation is complete after 
calling RasHangUp. It should wait for one of the preceding conditions before exiting. 


Paused States 


During a connection operation, there can be times when the remote server cannot 
proceed without additional information from the local user. Beginning with Microsoft® 
Windows NT® version 3.5, the RasDial function supports paused states. A paused state 
allows the Remote Access Connection Manager to suspend a connection ohelalen so 
the RAS client application can collect information from the user. 


Paused states are useful in the following situations: 


e When the user needs to provide a callback number. 


e When the user authentication fails, the user can type in a different user name and 
password. | 


e When the user’s password has expired, the user can provide a new password. 
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By default, paused state support is disabled. RAS clients that want to support paused 


_ states must set the RDEOPTS_PausedStates flag in the RASDIALEXTENSIONS 


structure passed as a parameter to RasDial. 


When a paused state occurs, the Remote Access Connection Manager invokes the 
client’s notification handler. If paused state support is disabled, the notification message 
indicates an error, and the connection operation fails. If it is enabled, the Connection 
Manager pauses the connection operation to wait for the RAS client’s response. The 
RAS client can resume the connection operation by a second RasDial call, or terminate 
it by calling the RasHangUp function. 


After getting the user’s input, the RAS client restarts the connection operation by calling 


-RasDial again. This second RasDial call must specify the following information: 


e The connection handle that was returned by the original RasDial call. 
e The same notification handler as the original RasDial call. 


e The user's input in the appropriate members of the RASDIALPARAMS structure. 


Other members of the RASDIALPARAMS structure should have the same 
information as specified in the original RasDial call. 


The second RasDial call cannot be made from within the notification handler. 


Callback Connections 


RAS supports connections in which the remote server hangs up and then calls back to 
the client to establish the connection. 


For each user that can connect to a RAS server, the server stores a callback attribute 
that controls how the connection is made. The default attribute is No Callback, which 
means that the user can connect to the RAS server without a callback. Alternatively, the 
administrator of the RAS server can assign to a user either the Preset or Set-By-Caller 
callback attribute. | 


For a user assigned the Preset restriction, the administrator specifies a phone number | 
that the RAS server must call back to establish a connection. The user cannot specify a 
different number, and the connection cannot be made without a callback. 


A Preset callback operation is handled automatically by the Remote Access Connection 


_Manager and the remote server. The RAS client application does not need to do 
- anything other than provide feedback to the user when the notification handler is called 


during the various states of the callback operation. 


A user assigned the Set By Caller privilege can choose to connect either with or without 
a callback. The RasDial call uses the szCallBackNumber member of the 


~ RASDIALPARAMS structure to indicate the choice. 
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The szCallBackNumber member can simply specify the callback number; or, to 
establish the connection without a callback, szCallBackNumber can point to an empty — 
string, “’. In either of these cases, the Remote Access Connection Manager handles the - 
connection operation automatically. As with a Preset callback operation, the RAS client 
does not need to perform any action other than to provide feedback to the user. 


If the RasDial call enables paused states, szCallBackNumber can point to an asterisk 
string, “*”, to indicate that the connection operation should enter a paused state to allow 
the user to type in the callback number. In this case, the connection operation for a Set. 
By Caller user enters a paused state after the remote server has authenticated the user. 
During the paused state, the RAS client gets the callback number input from the user. 
The client then resumes the connection operation by making a second RasDial call in 
which szCallBackNumber specifies the number supplied by the user. 


Note If paused states are not enabled there is a different meaning when 
szCallBackNumber points to an asterisk string, “*”. In this case, the asterisk indicates 
that the callback number is stored in the phone-book file specified by the RasDial call. 


-Disconnecting 


When a RAS client application starts a connection operation, the RasDial call receives" 
an HRASCONN connection handle to identify the connection. If the returned handle is 
not NULL, the client must eventually call the RasHangUp function to end the connection. 
lf an error occurs during the connection operation, the client must call HasHangUp even 
though the connection was never established. : | 


The application that calls RasHangUp should not exit immediately, because the Remote 
Access Connection Manager needs time to properly terminate the connection. Instead, 
the application should wait until the RasGetConnectStatus function returns 

ERROR_ INVALID_ HANDLE, indicating that the connection has been deleted. 


A RAS client application might need to end a connection even though it does not have 
_ the handle returned by RasDial. For example, the application that called RasDial might 

have exited once the connection was successfully established. In this case, the 
disconnecting application can use the RasEnumConnections function to get all the 
current connections. For each connection, RasEnumConnections returns a RASCONN| 
structure containing the HRASCONN connection handle and the phone-book entry | 
name or phone number specified when the connection operation was started. This 
information can be used to display a list of connections from which the user can select 
the connection to end. | 


RAS Custom Scripting 


Developers can create a custom-scripting DLL that resides on a RAS client computer. 
This DLL can communicate with the server during the piocess’ of Se a 
connection. 
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Setting Up the DLL 


To set up the DLL, create a value with the name CustomScriptDIIPath under the 
following registry key: | 


\HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Rasman\ 
Parameters\ 


This value should be of type REG_EXPAND_SZ. The value should contain the path to 
the custom-scripting DLL. Only one custom-scripting DLL is supported for each RAS 
client computer. 


Configuring the Phone-Book Entries 


RAS will invoke RasCustomScriptExecute for a connection only if the ehoné: -book 
entry for the connection has the RASEO_CustomScript option set. See the dwfOptions 
member of RASENTRY for a description of phone-book entry options. Use the 
RasGetEntryProperties and RasSetEntryProperties functions to set this option 
programmatically. 


Interaction Between the Server, RAS, and the 
Custom-Scripting DLL 


The custom scripting DLL should export a single entry point: 
RasCustomScriptExecute. RAS will call this function during the RASCS_Interactive 
state of the connection process. The RASCS_Interactive state is a paused state, which 
allows the user to interact with a user interface presented by the custom-scripting DLL. 
See RASCONNSTATE for more information about connection states. 


RAS will pass as parameters to the RasCustomScriptExecute function: 


e A handle to the port on the client computer that is being used for the connection. 
e Strings that identify the phone book and entry for the connection. 


e RAS also passes in a handle to a window to enable the DLL to present a user 
interface. 


e A set of function pointers that the DLL can use to communicate with the server. 


See RasCustomScriptExecute for more information about these parameters. 


RAS mediates the dialog between the server and the custom-scripting DLL. Typically, 
the server initiates the dialog. For example, the server may request the user name and 
password of the user. 


RAS makes no assumptions about the type of server to which the client is connected. 
The server need not use Windows NT version 4.0 or Windows 2000. 
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RAS Phone Books 


Phone books provide a standard way to collect and specify the information that the 
Remote Access Connection Manager needs to establish a remote connection. Phone 
books associate entry names with information such as phone numbers, COM ports, and 
modem settings. Each phone- -book entry contains the information needed to establish a 
RAS connection. 


Windows NT/2000: Phone books are stored in phone-book files, which are text files that 
contain the entry names and associated information. RAS creates a phone-book file 
called RASPHONE.PBK. The user can use the main Dial-Up Networking dialog box to 
create personal phone-book files. The Win32 API does not currently provide support for 
creating a phone-book file. Some RAS functions, such as the RasDial function, have a 
parameter that specifies a phone-book file. If the caller does not specify a phone-book 
file, the function uses the default phone-book file, which is the one selected by the user 
in the User Preferences property sheet of the Dial-Up Networking dialog box. 


Windows NT version 4.0 provides the RasPhonebookDlg and RasEntryDlg functions 
that display the built-in RAS user interface that enable users to WOtls with phone books 
and phone-book entries. 


Windows 95: Dial-up networking stores phone-book entries in the registry rather than in 
a phone-book file. Windows 95 does not support personal phone-book files. Windows 95 
does not support the functions that display the built-in RAS dialog boxes. 


Phone-Book Entries 


Phone-book entries contain the information necessary to establish a RAS connection. A 
user or administrator can use the Dial-Up Networking dialog box to create, edit, and 
dial phone-book entries. 


Windows 95: Windows 95 supports a limited set of the Win32 functions for working with 
phone-book entries. You can use the RasCreatePhonebookEntry and 
RasEditPhonebookEntry functions to create or edit a phone-book entry. These 
functions display a dialog box in which the user can specify information about the phone- 
book entry. You can use the RasGetEntryDialParams and RasSetEntryDialParams 
functions to set or retrieve the connection parameters for a phone-book entry. The 
RasEnumeEntries function retrieves an array of RASENTRYNAME structures that 
contain the phone-book entry names. : 


Windows NT version 4.0 supports the functions described for Windows 95, as well as a 
number of additional functions that an application can use to work with phone books and 
phone-book entries. | 


The RasEntryDlg function displays a property sheet that enables the user to create, 
edit, or copy phone-book entries. The RasCreatePhonebookEntry and 
RasEditPhonebookEntry functions call the RasEntryDlg function. You can use the 
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RasRenameEntry function to rename a phone-book entry, or the RasDeleteEntry to 
delete an entry. The RasValidateEntryName determines whether a specified string has 
the correct format to be used as an entry name. 


You can use the RasGetEntryProperties and RasSetEntryProperties to get and set 
additional information about a phone-book entry. These functions use a RASENTRY 
structure. 


The RasGetCredentials and RasSetCredentials functions get and set the user 
credentials associated with a specified RAS phone-book entry. These functions use a 
RASCREDENTIALS structure. 


The RasGetCountryinfo function retrieves country-specific dialing information from the 
Windows Telephony list of countries. RasGetCountrylinfo uses the RASCTRYINFO 
structure. 


Subentries and Multilink Connections 


Windows NT version 4.0 provides support for phone-book subentries, which enable 
multilink connections. A multilink connection combines the bandwidth of multiple 
connections to provide a single connection with higher bandwidth. 


A RAS phone-book entry can have zero or more subentries. The 
RasGetEntryProperties function retrieves a RASENTRY structure that includes 
information about the subentries of a phone-book entry. The dwSubEntries member of 
the RASENTRY structure indicates the number of subentries. Phone-book entries 
initially have no subentries. To add subentries to a phone-book entry, use the 
RasSetSubEntryProperties function. 


The properties for each subentry include a phone number and the name and type of the 
TAPI device to use when dialing the subentry. In addition, a subentry can include a list of 
alternate phone numbers to dial if RAS cannot make a connection using the primary 
number. The RasSetSubEntryProperties and RasGetSubEntryProperties functions 
use the RASSUBENTRY structure to set and retrieve the properties of a specified 
phone-book subentry. Subentries are identified by a one-based index. 


You can call the RasSetEntryProperties function to configure a multilink RAS entry to 


connect all subentries when it is first dialed. Alternatively, you can configure an entry to 


provide variable bandwidth. In this case, RAS connects a single subentry initially, and 
then connects or disconnects additional subentries as needed. For a variable-bandwidth 
multilink connection, you can use the RASDIALPARAMS structure to specify the initial 
subentry to connect when you call the RasDial function. When using the RasDialDig 
function to connect a multilink entry, you can use the RASDIALDLG¢ structure to specify 
the initial subentry to connect. 


For a variable-bandwidth multilink connection, use the RASENTRY structure with the 
RasSetEntryProperties function to specify the parameters for connecting and 
disconnecting the individual subentries. RAS connects an additional subentry when the 
bandwidth being used exceeds a choos percentage of the available bandwidth for a 
specified interval. 
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If you call the RasDial function to establish a multilink connection, you can specify a 
RasDialFunc2 callback function to receive notifications about the connection. 
RasDialFunc2 is similar to the RasDialFunc1 callback function, except that it provides 
additional information for a multilink connection, such as the index of the subentry that. 
caused the notification. RAS calls your RasDialFunc2 function when t connects or 
disconnects a subentry. 


You can use an HRASCONN connection handle to hang up or retrieve information about 
a multilink connection. You can get a connection handle for each of the subentry 
connections that make up the multilink, as well as for the combined multilink connection. 
When you call the RasDial function to establish a multilink connection, RasDial returns a 

_ handle to the combined multilink connection. Similarly, RasEnumConnections returns 
the combined multilink handle when you enumerate connections. To get a handle to one 
of the subentry connections in a multilink connection, call the RasGetSubEntryHandle 
function. | 


You can use the combined multilink connection handle and the subentry connection 
handles in the RasHangUp, RasGetConnectStatus, and RasGetProjectionInfo 
functions. Calling RasHangUp with a combined multilink handle terminates the entire 
connection; calling it with a subentry handle hangs up only that subentry connection. 
Similarly, RasGetConnectStatus returns information for the combined or individual 
connection, depending on the handle specified. The projection information returned by 
RasGetProjectioninfo for a multilink entry is the same for each of the subentry 
connection handles as it is for the main connection handle. 


RAS AutoDial 


Windows NT version 4.0 supports a feature known as AutoDial. Windows 95 and 
Windows NT version 3.51 and earlier do not support the AutoDial feature. 


~ When an attempt to connect to a network address fails because the host cannot be 
reached, the AutoDial feature can automatically start a dial-up connection operation. To 
do this, AutoDial searches its database of network addresses to ine a phone-book entry 
: that it can use to establish the connection. 


‘AutoDial Mapping Database 


The AutoDial mapping database maps network addresses to RAS phone-book entries. 
The database can include IP addresses (for example, “127.95.1.4”), Internet host names 
(for example, “www.microsoft.com’), or NetBIOS names (for example, “products1”). 
Associated with each address in the AutoDial database is a set of one or more 
RASAUTODIALENTRY entries. Each of these entries specifies a phone- -book entry that 
RAS can dial to connect to the address from a particular Telephony Application © 
Programming Interface (TAPI) dialing location. For more Information about TAPI dialing 
locations, see the TAP/ documentation. 
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AutoDial automatically creates entries in the AutoDial mapping database in two 
situations: 


e When an attempt to connect to a network address fails 


If there is no entry for the address in the mapping database, and the computer is not 
connected to a network (either directly or through RAS), AutoDial prompts the user to 
specify the information necessary to establish a dial-up connection. If the user 
provides the information and the dial-up connection operation is successful, AutoDial 
stores the information in the mapping database. 


e When the computer is connected to a network through RAS 


Whenever the user connects to a network address, AutoDial creates an entry in the 
database. The entry maps the network address to the phone-book entry that was 
used to establish the RAS connection. 


You can use the RasSetAutodialAddress function to add an address to the AutoDial 
mapping database, delete an address from the database, or change the AutoDial entries 
associated with an existing address in the database. You can use the 
RasGetAutodialAddress function to retrieve the AutoDial entries associated with a 
specified network address in the AutoDial mapping database. The 
RasEnumAutodialAddresses agen returns a list of all addresses in the AutoDial 
mapping database. 


-AutoDial Connection Operations 


When an attempt to connect to a network address fails because the host cannot be 
reached, the system searches the AutoDial mapping database for the address. If the 
address is in the database, the system initiates an AutoDial operation for the 
RASAUTODIALENTRY, if any, that corresponds to the local TAPI dialing location. 


The Win32 API provides functions that enable you to set and query AutoDial parameters 
that control AutoDial connections. You can call the RasSetAutodialEnable function to 
enable or disable the AutoDial feature for a specified TAPI dialing location. The 
RasGetAutodialEnable function indicates whether the AutoDial feature is enabled for a 
specified TAPI dialing location. For more information about TAPI dialing locations, see 
the TAPI documentation. You can call the RasSetAutodialParam function to set other 
AutoDial connection parameters. For example, you can disable AutoDial connections for 
the current logon session. Call the RasGetAutodialParam function to determine the 
current value of the AutoDial connection parameters. © 


The system provides a default user interface for AutoDial dialing operations. However, 
you can create an AutoDial dynamic-link library (DLL) to provide a custom user interface 


for AutoDial dialing operations involving specified phone-book entries. Your AutoDial 


DLL must ExpOWe both an ANSI and a Unicode version of a RASADFunc AutoDial 
handler. 
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To enable your custom AutoDial handler for a phone-book entry, call the 
RasSetEntryProperties function to set the properties for that entry. The szAutodialDIl 
and szAutodialFunc members of the RASENTRY structure passed to 
RasSetEntryProperties specify the name of your AutoDial DLL and the name of your 
RASADFunc function, excluding the “A” or “W” suffix. 


When the system starts an AutoDial operation for a phone-book entry with a custom 
AutoDial handler, it calls the specified RASADFunc. The RASADFunc function receives 
a pointer to a RASADPARAMS structure that indicates the location and parent window 
for the window of your user interface. Your RASADFunc can start a thread to perform _ 
the custom dialing operation. The RASADFunc function returns TRUE to indicate that it 
took over the dialing, or FALSE to allow the system to perform the dialing. Your custom 
dialing operation must use the RasDial function to do the actual dialing. When the 
dialing operation has been completed, the custom dialing operation indicates success or 
failure by setting the variable pointed to by the Pawn od? parameter passed to 
Aeoe eee: 


RAS Configuration and Connection Information 


Applications running on Windows NT version 4.0 and later versions, and Windows 95, 
can use the RasEnumConnections function to get information about the existing 
connections on the local computer. The information for each connection includes a 
connection handle and the name of the phone-book entry used to establish the 
connection. You can use the connection handle in a call to the RasGetConnectStatus 
function get the current status of the connection. 


Windows NT 4.0 and later versions provide two new functions for retrieving RAS 
information. Windows 95 does not support these functions. 


The RasEnumDevices function returns the name and type of the RAS-capable devices | 
that are configured on the local computer. 


The RasConnectionNotification function specifies an event object that the eyelen 
signals when a RAS connection is created or terminated. 


RAS Server Administration 


Windows NT version 4.0 provides a set of functions for administering user permissions 
and ports on Windows NT/Windows 2000 RAS servers. Windows 95 does not support 
these functions. Using these functions, you can develop a RAS server administration 
application to perform the following tasks: 

e Enumerate those users who have a specified set of RAS permissions 

e Assign or revoke RAS permissions for a specified user 

e Enumerate the configured ports on a RAS server 

e Get information and statistics about a specified port on a RAS server 
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e Reset the statistics counters for a specified port 
e Disconnect a specified port 


You can also install a RAS server administration DLL for auditing user connections and 
assigning IP addresses to dial-in users. The DLL exports a set of functions that the RAS 
server calls whenever a user tries to connect or disconnect. 


RAS User Account Administration 


A Windows NT version 4.0 RAS server uses a user account database that contains 
information about a set of user accounts. The information includes a user’s RAS 
privileges, which are a set of bit flags that determine how the RAS server responds when 
the user calls to connect. The RAS server administration functions enable you to locate 
the user account database, and to get and set the RAS privileges for user accounts. 


A Windows NT version 4.0 RAS server can be part of a Windows NT/Windows 2000 
domain, or it can be a stand-alone Windows NT Server or Workstation that is not part of 
a domain. For a server that is part of a domain, the user account database is stored on 
the Windows NT/Windows 2000 server that is the Primary Domain Controller (PDC). A 
stand-alone server stores its own local user account database. To get the name of the 
server that stores the user account database used by a specified RAS server, you can 
call the RasAdminGetUserAccountServer function. You can then use the name of the 
user account server in a call to the NetQueryDisplayInformation function to enumerate 
the users in a user account database. You can also use the server name in calls to the 
RasAdminUserGetInfo and RasAdminUserSetiInfo functions to get and set the RAS 
privileges for a specified user account. 


The RasAdminUserGetinfo and RasAdminUserSetinfo functions use the 
RAS_USER_0 structure to specify a user’s RAS privileges and call-back phone number. 
The RAS privileges indicate the following information: 


e Whether the user can make a remote connection to the server or the domain to which 
the server belongs. _ 7 | 


e Whether the user can establish a connection through a call-back, in which the RAS — 
server hangs up and then calls back to the user to establish the connection. 
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Each user account specifies one of the following flags to indicate the user’s call-back 


privilege. 
Value al Meaning 
RASPRIV_NoCallback | | The RAS server will not call back the user to establish 


a connection. 


RASPRIV_AdminSetCallback When the user calls, the RAS server hangs up and 
oe calls a preset call-back phone number stored in the _ 
user account database. The szPhoneNumber 
member of the RAS_USER_0 structure contains the 
user’s Call-back phone number. 


RASPRIV_CallerSetCallback When the user calls, the RAS server provides the _ 
option of specifying a call-back phone number. The 
user can also choose to connect immediately without 
a call back. The szPhoneNumber member contains a 
default number that the user can override. 


RAS Server and Port Administration 


The RAS server administration functions enable you to get information about a specified 
RAS server and its ports. These functions also enable you to terminate a connection on 
a specified RAS server port. 


The RasAdminServerGetinfo function returns a RAS_SERVER_0 structure that 
contains information about the configuration of a RAS server. The returned information 
includes the number of ports currently available for connection, the number of ports 
currently in use, and the server version number. 


The RasAdminPortEnum function retrieves an array of RAS_ PORT_0 structures that 
contains information for each of the ports configured on a RAS server. The information 
_ for each port includes: 


e@ The name of the port 
e Information about the device attached to the port 


e Whether the case server associated with the port is a Windows NT/Windows 2000 
Server 


o _ Whether the port is currently: in use, and if it is, information about the connection 


You can. call the RasAdminPortGetInfo function to get additional information about a 
specified port on a RAS server. This function returns a RAS_PORT_1 structure that 

_ contains a RAS_PORT_0 structure and additional information about the current state of 
the port. The RasAdminPortGetinfo function also returns an array of 
RAS_PARAMETERS structures that describe the values of any media-specific keys | 
associated with the port. A RAS. PARAMETERS structure uses a value from the 
RAS_PARAMS _ FORMAT enumeration to indicate the format of the value for each | 
media-specific key. 
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The RasAdminPortGetinfo function also returns a RAS_PORT_STATISTICS structure 


that contains various statistic counters for the current connection, if any, on the port. For 


a port that is part of a multilink connection, RasAdminPortGetinfo returns statistics for 


_ the individual port and cumulative statistics for all ports involved in the connection. You 


can use the RasAdminPortClearStatistics function to reset the statistic counters for the 


port. The RasAdminPortDisconnect function disconnects a port that is in use. 


Use the RasAdminFreeBuffer function to free memory allocated by the 
RasAdminPortEnum and RasAdminPortGetinfo functions. Use the 
RasAdminGetErrorString function to get a string that describes a RAS error code 
returned by one of the RAS Server Administration (RasAdmin) functions. | 


RAS Administration DLL 


Windows NT version 4.0 enables you to install a RAS administration DLL on a 
Windows NT version 4.0RAS server. The DLL exports functions that the RAS server 
calls whenever a user tries to connect or disconnect. You can use the DLL to perform 
the following administrative functions: 


e Decide whether to allow a user to connect to the server. This can provide a security 
check in addition to the standard RAS user authentication. 


e Record the time that each user connects to and disconnects from the server. This can 
be useful for billing or auditing purposes. 


e Assign an IP address to each user. This can be useful for security purposes to map a 
user’s connection to a specific computer. 


Implement the following functions when developing a RAS server administration DLL. 


e RasAdminAcceptNewConnection 

e RasAdminConnectionHangupNotification 
e RasAdminGetlpAddressForUser 

° RasAdminReleaselpAddress 


A RAS administration DLL must implement and export all of the above functions. If any 
of the functions are not implemented, the remote access service will fail to start. 


The RasAdminAcceptNewConnection and 
RasAdminConnectionHangupNotification functions enable the DLL to audit user 


connections to the server. A Windows NT/Windows 2000 RAS server calls the 


RasAdminAcceptNewConnection function whenever a user tries to connect. The 
function can prevent the user from connecting. You can also use the function to 
generate an entry in a log for billing or auditing. When the user disconnects, the RAS 
server Calls the RasAdminConnectionHangupNotification function, which can log the 
time at which the user disconnected. 
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After the RAS server has authenticated a caller, it calls the 
RasAdminGetlpAddressForUser function to get an IP address for the remote client. 

- The DLL can use this function to provide an alternate scheme for mapping an IP address 
to a dial-in user. lf RasAdminGetlpAddressForUser is not implemented, a RAS server 
connects a remote user to an IP address selected from a static pool of IP addresses, or 
one selected by a Dynamic Host Configuration Protocol (DHCP) server. The 
RasAdminGetlpAddressForUser function allows the DLL to override this default IP 
address and specify a particular IP address for each user. The 
RasAdminGetlpAddressForUser function can set a flag that causes RAS to call the 
RasAdminReleaselPAddress function when the user disconnects. The DLL can use 
RasAdminReleaselPAddress to update its user-to-IP-address map. 


RAS serializes calls into the administration DLL. A call into one of the DLL’s functions for 
a given RAS client will never be preempted by a call to that function for a different RAS 
client; the initial call is guaranteed to be complete before RAS calls the function for the 
other client. Furthermore, serialization extends to certain groups of functions. The IP 
address functions are serialized as a group; a call into either 
RasAdminGetlpAddressForUser or RasAdminReleaselpAddress will block calls into 
both until the initial call is complete. RasAdminAcceptNewConnection and 
RasAdminConnectionHangupNotification are also serialized as a group. 


RAS executes the functions for assigning IP addresses in one process and executes the 
functions for connection and disconnection notifications in another process. | 
Consequently, the DLL should not depend on shared data between the two sets of 
functions. | 


The RAS server logs an error in the system event log if an error occurs when it tries to 
load a RAS administration DLL or when calling one of the DLL’s functions. This can 
happen, for example, if the DLL specified the wrong name for an exported function, or if 
it did not include the function name in the .def file. The entry in the event log indicates 
the reason for the failure. 


Windows 2000 and later: RAS administration DLLs that implement this function 
interface will not work on Windows 2000 and later versions. Instead, use the MprAdmin 
function interface provided with the more recent versions of Windows. For more 
information, see the RAS Administration Reference in the Routing and RAS 
documentation. 


RAS Administration DLL Registry Setup 


The setup program for a third-party RAS administration DLL must register the DLL with 
RAS by providing information under the following key in the registry: 


HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIll 
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To register the DLL, set the following values under this key. 


Value name Value data 

DisplayName _ A REG_SZ string that contains the user-friendly display name of 
| | : the DLL. 

DLLPath | A REG_SZ string that contains the full path of the DLL. 


For example, the registry entry for a RAS administration DLL from a fictional company 
named Netwerks Corporation might be: 


HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminbDIll 
DisplayName : REG_SZ : Netwerks RAS Admin DLL 
DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll 


The setup program for a RAS administration DLL should also provide remove/uninstall 
functionality. If a user removes the DLL, the setup program should delete the Pees 
registry entries. 


RAS Security Host Support 


Windows NT version 4.0 provides a way for a third-party RAS security DLL to enhance 
the built-in RAS security features. Windows 95 does not provide this support. 


The Windows NT/Windows 2000 RAS server provides security mechanisms for 

validating the network access of remote users. When a RAS server receives a call, it 
validates the user’s credentials against the local or domain account database. RAS also 
supports call-back security, in which the RAS server hangs up and then calls back to the 

remote user to establish the connection. For networks in which this level of security is 
not enough, you can install a third-party RAS security DLL. The security DLL can then 
authenticate a remote user by reading security information from a database other than 
the standard Windows NT/Windows 2000 user account database. 


When the RAS server receives a call, it invokes the security DLL to authenticate the 
remote user. The RAS security host support provides a mechanism for the security DLL 
to communicate with the remote user through a terminal window on the remote 
computer. In a typical scenario, the security DLL asks for the logon name of the remote 
user. The DLL then uses its private security database to formulate a challenge to send to 
the remote terminal. For example, the challenge could be a code that the user must 
provide as input to a cardkey reader. The cardkey reader then displays a response that 
the remote user types in the terminal window. The security DLL then validates the 
response against the user’s information in the private security database. 


If the security DLL authenticates the remote user, the RAS server performs its own 
authentication. This ensures that RAS security always authenticates a remote user, even 
ifa security DLL is installed that grants access to all users. 
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Note Windows NT/Windows 2000 currently provides RAS security host support only for 
asynchronous connections; other media, such as ISDN, are not supported. 


Registering a RAS Security DLL 


The setup program for a RAS security DLL must register the DLL with the 

Windows NT/Windows 2000 RAS server. Only one RAS security DLL can be registered; 
Windows NT/Windows 2000 does not support multiple security DLLs. To register a RAS 
security DLL, set the DLLPath value under the following key in the registry: 


Value Name Value Data 


DLLPath A REG_SZ string that contains the path of the DLL. This string 
should specify the full path unless the DLL is in a directory listed 
in the system path. 


The setup program for a RAS security DLL must also provide remove/uninstall 
functionality. If a user removes the DLL, the setup program must delete the DLLPath 
value from the registry. The RAS service will not start if the DLLPath value specifies a 
DLL that cannot be found. 


A RAS security DLL must export the RasSecurityDialogBegin and 
RasSecurityDialogEnd functions. 


RAS Server Security Authentication 


When a Windows NT/Windows 2000 RAS server receives a call, it invokes the 
RasSecurityDialogBegin function of the registered RAS security DLL, if there is one. 
This call notifies the security DLL to begin its authentication. of the remote user. The RAS 
server calls RasSecurityDialogBegin before performing its PPP or RAS authentication. 


The RasSecurityDialogBegin call passes the following information to the security DLL: 
oA port handle to identify the connection | 


e Pointers to buffers to use when communicating with the remote user 


e Apointer to a RasSecurityDialogComplete function to call when the authentication 
has been completed 


The port handle and buffer pointers are valid until the security DLL calls. 
_ RasSecurityDialogComplete to terminate the authentication transaction. 
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The RasSecurityDialogComplete notifies the RAS server of the results of the security 
DLL’s authentication of the remote user. If the security DLL reports success, the RAS 
server proceeds with its PPP and RAS authentication of the remote user. If the security 
DLL reports that the remote user failed the authentication, or that.an error occurred, the 
RAS server hangs up and logs the error or failed authentication in the 

Windows NT/Windows 2000 event log. 


RAS Security DLL Authentication Transaction 


The Windows NT/Windows 2000 RAS server calls the security DLL’s 
RasSecurityDialogBegin function to begin an authentication of a remote user. The RAS 
server is blocked and cannot accept any other calls until RasSecurityDialogBegin 
returns. For this reason, RasSecurityDialogBegin should copy the input parameters, 
create a thread to perform the authentication, and return as quickly as possible. 


The thread created by the security DLL uses the RasSecurityDialogSend and 
RasSecurityDialogReceive functions to communicate with the remote computer. These 
functions are not available for static import from any library. Instead, the security DLL 
must use the LoadLibrary and GetProcAddress functions to dynamically link to these 
functions in RASMAN.DLL. 


During an authentication transaction, the RAS connection manager on the remote 
computer displays a terminal window. The thread of the security DLL calls 
RasSecurityDialogSend to send a message to display in the terminal window. The 
thread then calls RasSecurityDialogReceive to receive the input that the remote user 
types in the terminal window. The thread can make any number of 
RasSecurityDialogSend calls, with each call followed by a RasSecurityDialogReceive 
call. After each call to RasSecurityDialogReceive, the thread must call one of the wait 
functions, such as WaitForSingleObject, to wait for the asynchronous send and receive 
operations to be completed. The RAS server signals an event object when the receive 
operation has been completed or when an optional time-out interval has elapsed. 


When the thread has finished authenticating the remote user, it calls the - 
RasSecurityDialogComplete function. This call passes a SECURITY_MESSAGE 
structure containing the results of the authentication transaction to the RAS server. The 
RAS server then performs a cleanup sequence that includes a call to the DLL’s 
RasSecurityDialogEnd function. This gives the security DLL an opportunity to perform 
any necessary cleanup. 


The security DLL can call the RasSecurityDialogGetInfo function to retrieve information 
about the port associated with an authentication transaction. RasSecurityDialogGetinfo 
fills in a RAS_SECURITY_INFO structure that indicates the state of the last 
RasSecurityDialogReceive call for the port. 
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Using Remote Access Service 


The following section explains how to use Remote Access Service features in an 
application. 


Linking to the Remote Access DLL 


If an application links statically to the RASAPI32 DLL, the application will fail to load if 
Remote Access Service is not installed. A RAS application can load when RAS is not 
installed by using LoadLibrary to load the DLL, and GetProcAddress to obtain pointers 
to the RAS functions. 


The Win32 RAS functions are in RASAPI32.DLL. The import library for these functions is 
RASAPI32.LIB. To use the RAS functions, your programs must include the following 


files. 
File Description 
RAS.H Contains the RAS function prototypes, constants, and structure 


definitions. 
RASERROR.H Contains the RAS error codes. 
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RAS Functions 


Use the following functions to implement RAS functionality: 


ORASADFunc 

RASADFunc 
RasClearConnectionStatistics 
RasClearLinkStatistics 
RasConnectionNotification 
RasCreatePhonebookEntry 
RasCustomDeleteEntryNotify 
RasCustomDial 
~RasCustomDialDlg 
RasCustomEntryDig 
‘RasCustomHangUp 
RasDeleteEntry 

-RasDial © 

RasDialDlig 

RasDialFunc 

RasDialFunct 
-RasDialFunc2 
RasEditPhonebookEntry 
RasEntryDig — | 
RasEnumAutodialAddresses 
RasEnumConnections 
RasEnumDevices 
RasEnumEntries 

_ RasFreeEapUserldentity 
RasGetAutodialAddress 
RasGetAutodialEnable | 
RasGetAutodialParam 
RasGetConnectionStatistics 
RasGetConnectStatus 


RasGetCountryinfo- 
RasGetCredentials 
RasGetCustomAuthData 
RasGetEapUserData 
RasGetEapUserldentity 
RasGetEntryDialParams 
RasGetEntryProperties | 
RasGetErrorString 
RasGetLinkStatistics 
RasGetProjectioninfo | 
RasGetSubEntryHandle 


_ RasGetSubEntryProperties 


RasHangUp 
RasinvokeEapuUl 
RasMonitorDlig 


_ RasPBDIgFunc 
‘RasPhonebookDlig 


RasRenameEntry © 
RasSetAutodialAddress 
RasSetAutodialEnable 
RasSetAutodialParam 
RasSetCredentials 
RasSetCustomAuthData 
RasSetEapUserData | 


RasSetEntryDialParams _ 


RasSetEntryProperties 
RasSetSubEntryProperties 
RasValidateEntryName 


ORASADFunc 


The ORASADFunc function is an application-defined callback funeton that you can use | 
to provide a customized user interface for autodialing. : 
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This prototype is provided for compatibility with earlier versions of Windows. New 
applications should use the RASADFunc callback function. Support for this prototype 
may be removed in future versions of RAS. | 


arameters 


hwndOwner 
Handle of the owner window. 


loszEntry | 
Pointer to a null-terminated string that specifies the phone book entry to use. 


dwFlags 
Reserved; must be zero. 


lpdwRetCode | 
Pointer to a variable that the callback function fills in with the results of the dialing . 
operation. If the dialing operation succeeds, set this variable to ERROR_SUCCESS. If 
the dialing operation fails, set it to a nonzero value. 


Return Values 


lf the callback function performs the dialing operation, return TRUE. Use the 
lodwRetCode parameter to indicate the results of the dialing operation. 


If the callback function does not perform the dialing operation, return FALSE. In this 
case, the system uses the default user interface for dialing. : 


Remarks 


If your ORASADFunc function performs the dialing operation, it presents its own user 
interface for dialing and calls the RasDial function to do the actual dialing. Your | 
ORASADFunc then returns TRUE to indicate that it took over the dialing. When the 
dialing operation has been completed, set the variable pointed to by jJodwRetCode 

to indicate success or failure. | 


To enable an ORASADFunc handler for a phone book entry, use the RASENTRY 
structure in a call to the RasSetEntryProperties function. The szAutodialDIl member 
specifies the name of the DLL that contains the handler, and the szAutodialFunc 
member specifies the exported name of the handler. 


The ORASADFunc function is a placeholder for the library-defined function name. 
The ORASADFUNC type is a pointer to an ORASADFunc function. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASADFunc, RasDial, RASENTRY, RasSetEntryProperties 


RASADFunc 


The RASADFunc function is an application-defined callback function that you can use to 
provide a customized user interface for autodialing. 


Parameters 


IpszPhonebook _ 
Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a phone book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog box. 


lpszEntry 
Pointer to a null-terminated string that specifies the phone book entry to use. 


loAutoDialParams 
Pointer to a RASADPARAMS structure that indicates how to position the window of 


your AutoDial user interface. The structure may also specify a parent window for your 
AutoDial window. 


lodwRetCode 
Pointer to a variable in which you must return a value if you perform the dialing 
operation. If the dialing operation succeeds, set this variable to ERROR_SUCCESS. If 
the dialing operation fails, set it to a nonzero value. 
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Return Values 


lf your application performs the dialing operation, return TRUE. Use the IpdwRetCode 
parameter to indicate the results of the dialing operation. 


lf your application does not perform the dialing operation, return FALSE. In this case, the 
system uses the default user interface for dialing. 


Remarks 


When the system starts an AutoDial sper on for a phone book entry with a custom 
AutoDial handler, it calls the specified RASADFunc. Your RASADFunc can start a 
thread to perform the custom-dialing operation. The RASADFunc function returns TRUE 
to indicate that it took over the dialing, or FALSE to allow the eyelem to perform the 
dialing. 


If your RASADFunc function performs the dialing operation, it presents its own user 
interface for dialing and calls the RasDial function to do the actual dialing. Your 
RASADFunc then returns TRUE to indicate that it took over the dialing. When the 
dialing operation has been completed, set the variable pointed to by the jodwRetCode 


parameter to indicate success or failure. 


Your AutoDial DLL must provide both a RASADFUNCA (ANSI) and a RASADFUNCW 
(Unicode) version of the RASADFunc handler. To enable a RASADFunc AutoDial 
handler for a phone book entry, use the RASENTRY structure in a call to the 
RasSetEntryProperties function. The szAutodialDIl member specifies the name of the 
DLL that contains the handler, and the szAutodialFune member specifies the exported 
name of the handler. The szAutodialFunc member should not include the “A” or “W” 
suffix. 


RASADFunc is a placeholder for the library-defined function name. The RASADFUNC 
type is a pointer to a RASADFunc function. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Unicode: Declared as Unicode and ANSI prototypes. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, 


RASENTRY, RasSetEntryProperties 
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RasClearConnectionStatistics 


The RasClearConnectionStatistics functions clears any accumulated statistics for the 
specified RAS connection. 


Parameters 

hRasConn 
Handle to the connection. Use RasDial or RasEnumConnections to obtain this 
handle. 


Return Values 
If the function succeeds, the return value is ERROR _SUCCESS. 


If the function fails, the return value is one of the following error codes. 


Value Meaning 

ERROR_INVALID_HANDLE — The hRasConn parameter does not specify a valid 

| | connection. 

ERROR_NOT_ENOUGH_ The function could not allocate sufficient memory to 
MEMORY | complete the operation. 

Other Use FormatMessage to retrieve the system error 


message that corresponds to the error code returned. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasClearLinkStatistics, RasDial, RasEnumConnections, 
RasGetConnectionStatistics, RAS_STATS 


RasClearLinkStatistics | 


The RasClearLinkStatistics functions clears any accumulated statistics for the 
specified link ina RAS multilink connection. | 


108 Volume 4 Remote Access Services 


Parameters 


hRasConn | 


Handle to the connection. Use RasDial or RasEnumConnections to obtain this 
handle. 


dwSubEntry 
Specifies the subentry that corresponds to the link for which to clear statistics. 


Return Values 
If the function succeeds, the return value is ERROR SUCCESS. 


If the function fails, the return value is one of the following error codes. 


Value Meaning 

ERROR_INVALID_HANDLE The hRasConn parameter does not specify a valid 
connection. 

ERROR_INVALID_ The dwSubEntry parameter is zero. 

PARAMETER 


ERROR_NO_CONNECTION — RAS could not find a connected port that corresponds 
to the value in the dwSubEntry parameter. 


ERROR_NOT_ENOUGH_ The function could not allocate sufficient memory to 
MEMORY complete the operation. 
Other Use FormatMessage to retrieve the system error 


message that corresponds to the error code returned. | 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasClearConnectionStatistics, RasGetLinkStatistics 
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RasConnectionNotification 


The RasConnectionNotification function specifies an event object that the system sets 
to the signaled state when a RAS connection is created or terminated. 


Parameters 


hrasconn 
Handle to the RAS connection for which to receive notifications. This can be a handle 
returned by the RasDial or RasEnumConnections function. If this parameter is 
INVALID-HANDLE_VALUE, you receive notifications for all RAS connections on the 
local computer. | 


hEvent — 


Specifies the handle of an event object. Use the CreateEvent function to create an 


event object. 
dwFlags 


Specifies the RAS event that causes the system to signal the event object specified — 
by the hEvent parameter. This parameter can be a combination of the following 


values. 
Value 


RASCN_Connection 


RASCN_ Disconnection 


RASCN_BandwidthAdded 


RASCN_BandwidthRemoved 


Meaning 


If hrasconn is INVALID_HANDLE_VALUE, hEvent is 
signaled when any RAS connection is created. 


hEvent is signaled when the hrasconn connection 
is terminated. If hrasconn is a multilink connection, 
the event is signaled when all subentries 

are disconnected. If hrasconn is 
INVALID_HANDLE_VALUE, the event is signaled 
when any RAS connection is terminated. 


Windows NT 4.0 and earlier versions only: If 
hrasconn is a handle to a combined multilink 
connection, hEvent is signaled when a subentry i is 
connected. 


Windows NT 4.0 and earlier versions only: If 
hrasconn is a handle to a combined multilink 
connection, hEvent is signaled when a subentry | is 


7 disconnected. 
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Return Values - 
If the function succeeds, the return value is zero. 


If the function fails, the return value is a nonzero error code. 


Remarks 
To determine when the event object is signaled, use any of the wait functions. 


When the event is signaled, you can use other RAS functions, such as 
RasEnumConnections, to get more information about the RAS connection that was 


created or terminated. 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Requires Windows 98. 
Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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RasCreatePhonebookEntry 


_ The RasCreatePhonebookEntry function creates a new phone book entry. The function 
displays a dialog box in which the user types information for the phone book entry. 


Windows NT/2000: The RasCreatePhonebookEntry function calls the RasEntryDlg 
function. Applications written for Windows NT version 4.0 should use RasEnitryDlg. 


Parameters 


hwnd 7 ae 
Handle to the parent window of the dialog box. 
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ice Phonebook 
Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a Phone Book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog box. 
Windows 95: Dial-up networking stores phone book entries in the registry amet than 
ina paene book file. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is the following error code. 


Value Description 
ERROR _CANNOT_ OPEN_ PHONEBOOK _ The phone book is corrupted or missing 
componenis. 


Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. : 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000, 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasEditPhonebookEntry, RasEntryDlg, RasGetEntryDialParams, 
-RasSetEntryDialParams 


RasCustomDeleteEntryNotify 


The RasCustomDeleteEntryNotify function is an application- defined function that is 
exported by a third-party custom-dialing DLL. This function allows third-party vendors to 
_ implement custom dialogs for managing phone book entries. 
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Parameters 


lpszPhonebook 
Pointer to a null-terminated string that specifies the full path and file name of a phone 
book (PBK) file. If this parameter is NULL, the function uses the current default phone 
book file. The default phone book file is the one selected by the user in the User 
Preferences property sheet of the Dial-Up Networking dialog box. 


IpszEntry 
Pointer to a null-terminated string that contains the name of the phone book entry to 
dial. 


dwFlags 
Specifies one or more of the following flags: 


RCD_SingleUser 
RCD_AllUsers 
RCD_Eap 


Return Values , 
The function should return NO_ERROR. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 


RasCustomDial, RasCustomDialDlg, RasCustomEntryDlg, RasCustomHangUp, 
RasDial, 


RasCustomDial | 


The RasCustomDial function is an application-defined function that is exported by a 
third-party custom-dialing DLL. This function allows third-party vendors to implement 
custom remote-access dialing routines. 
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Parameters 


hInstDIl 
Handle to the instance of the custom-dial DLL that was loaded. 


lpRasDialExtensions od « 
Pointer to a RASDIALEXTENSIONS structure that specifies a set of RasDial 
extended features to enable. If you do not need to enable any of the extensions, set — 
this parameter to NULL. 


lpszPhonebook 
Pointer to a null-terminated string that specifies the full path and file name of a phone 
book (PBK) file. If this parameter is NULL, the function uses the current default phone 
book file. The default phone book file is the one selected by the user in the User 
Preferences property sheet of the Dial-Up Networking dialog box. 


lpRasDialParams 
Pointer to a RASDIALPARAMS structure that specifies calling parameters for the 
RAS connection. 


The caller must set the RASDIALPARAMS structure’s dwSize member to 
sizeof(RASDIALPARAMS) to identify the version of the structure being passed. 


dwNotifierlype 
This parameter is the same as the dwNotifierType parameter for the RasDial function. 
see the RasDial reference page for more information. | 
IpvNotifier 
This parameter is the same as the /pvNotifier parameter for the RasDial function. 
See the RasDial reference page for more information. =| 


lphRasConn 
Pointer to a variable of type HRASCONN. You must set the HRASCONN variable to 
NULL before calling RasDial. If RasDial succeeds, it stores a handle to the RAS 
connection into *JohRasConn. 
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Return Values 


If the function succeeds, the immediate return value should be zero. In addition, the 
function should store a handle to the RAS connection into the variable pointed to by the 
IpohRasConn parameter. 


If the function fails, the immediate return value should be a nonzero error value, either 
from the set listed in Raserror.h or ERROR_NOT_ENOUGH_MEMORY. | 


Remarks 


RAS calls this entry point from RasDial, if the szCustomDialDIl member of the 
RASENTRY structure for the entry being dialed specifies a custom-dialing DLL. 


If this entry point calls RasDial, the /oRasDialExtensions parameter must not be NULL, 
and the dwFlags member of the RASDIALEXTENSIONS structure must have the 
RDEOPT_CustomDial flag set. 


If the custom-dial DLL does not support this entry point, RAS returns 
ERROR_CANNOT_DO_CUSTOMDIAL to the caller of RasDial. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Unicode: Declared as Unicode and ANSI prototypes. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasCustomDialDlg, RasCustomEntryDig, RasCustomHangUp, RasDial, 
RASENTRY 


RasCustomDialDlg | 


The RasCustomDialDlg function is an application-defined function that is exported by a 
third-party custom-dialing DLL. This function allows third-party vendors to implement 
custom RAS connection dialog boxes. 
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Parameters 


hinstDil 
Handle to the instance of the custom- laiing DLL that was loaded. 


dwFlags 
The parameter is reserved for future | use. 


loszPhonebook 
Pointer to a null-terminated string that specifies the full path and file name of a phone 
book (PBK) file. If this parameter is NULL, the function uses the current default phone 
book file. The default phone book file is the one selected by the user in the User 
Preferences property sheet of ine Dial- a Networking dialog box. 


IoszEntry 
Pointer to a null-terminated string that contains the name of the phone book ae to 
dial. 


IpszPhoneNumber 3 
Pointer to a null-terminated string that contains a phone number that overrides the 
numbers stored in the phone book entry. If this parameter is NUEL, RasDialDig uses 
_ the numbers in the phone book sauce 


Ipinfo 
Pointer to a RASDIALDLG structure that contains additional input and output 
parameters. On input, the dwSize member of this structure must specify 
sizeof(RASDIALDLG). If an error occurs, the dwError member returns an error code; 
otherwise, it returns zero. 


Return Values 


_ If the function establishes a RAS connection, the return value should be a nonzero 
value. 


If an error occurs, or if the user selects a Cancel button during “ik box eaeration: the 
return value should be zero. If an error occurs, set the dwError member of the 
| RASDIALDLG structure to a nonzero system errorora 1 RAS error code from Raserror.h. 


Remarks 


RAS will call this entry point from RasDialDIg, if the szCustomDialDil member of the 
-RASENTRY structure for the entry being dialed specifies a custom-dialing DLL. 
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If this entry point calls RasDial, the /oRasDialExtensions parameter must not be NULL, 
and the dwFlags member of the RASDIALEXTENSIONS siructure must have the 
RDEOPT_CustomDial flag set. 


The custom-dial dialog must support WM_COMMAND messages where 
LOWORD(wParam) equals IDCANCEL. 


If the custom-dial DLL does not support this entry point, RAS returns 
ERROR_CANNOT_DO_CUSTOMDIAL to the caller of RasDialDlg. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Rasdlg.h. 

Unicode: Declared as Unicode and ANSI prototypes. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasCustomDial, RasCustomEntryDlg, RasCustomHangUp, RasDialDlg, 
RASENTRY 


RasCustomEniryDlg 


The RasCustomEntryDlg function is an application-defined function that is exported by 
a third-party custom-dialing DLL. This function allows third-party vendors to implement 
custom dialogs for managing phone book entries. 


Parameters | 


hinstDil — , | 7 
Handle to the instance of the custom-dial DLL that was loaded. 
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loszPhonebook 
Pointer to a null-terminated string that specifies the full path and file name of a phone 
book (PBK) file. If this parameter is NULL, the function uses the current default phone 
book file. The default phone book file is the one selected by the user in the User 
Preferences property sheet of the Dial- “Up Networking dialog box. , 


loszEntry 
Pointer to a null-terminated string that contains the name of the phone book entry to 
edit, copy, or create. 


lf you are editing or copying an entry, this parameter is the name of an existing phone 
book entry. If you are copying an entry, set the RASEDFLAG_CloneEntry flag in the 
dwFlags member of the RASENTRYDLG structure. 


If you are creating an entry, this parameter is a default new entry name that the user 
can change. If this parameter is NULL, the function provides a default name. If you 
are creating an entry, set the RASEDFLAG _NewEntry flag in the dwFlags member of 
the RASENTRYDLG structure. 

lpInfo 
Pointer to a RASENTRYDLG structure that contains additional input and output 
parameters. On input, the dwSize member of this structure must specify 
sizeof(RASENTRYDLG). Use the dwFlags member to indicate whether you are 

— creating, editing, or copying an entry. If an error occurs, the dwError member returns 
an error code; otherwise, it returns zero. _ 


Return Values 
If the user creates, copies, or edits a shone book entry, the return value should be a 
nonzero value. 


If an error occurs, or if the user cancels the operation, the return value should be zero. If — 
an error occurs, the RasCustomEntryDlg should set the dwError member of the 

~ RASENTRYDLG structure to a nonzero system error code or a RAS error code from 
Raserror.h. 


Remarks 
RAS will call this entry point from RasEniryDlg, if the szCustomDialDII member of the 
RASENTRY siructure for the entry being dialed specifies a custom-dialing DLL. 


If the custom-dial DLL does not support this entry point, RAS returns 
ERROR_NO_CUSTOMENTRYDLG to the caller of RasEntryDig. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Rasdlg.h. 

Unicode: Declared as Unicode and ANSI prototypes. 
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Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasCustomDial, RasCustomDialDlg, RasCustomHangUp, RasEntryDig, 
RASENTRY | 


RasCustomHangUp 


The RasCustomHang Up function is an application- defined function that is exported by a 
third-party custom-dialing DLL. This function allows third- Pally vendors to implement 
custom connection hang-up routines. 


Parameters 


hRasConn © 
Handle to the RAS connection to hang up. 


Return Values 


If the function succeeds, the return value should be zero. 


If the function fails, the return value should be a nonzero error value listed i in ee h, 
or ERROR_INVALID HANDLE. 


Remarks 


RAS will call this entry point from RasHangUp, if the szCustomDialDIl member of the 
RASENTRY structure for the entry being dialed specifies a custom-dialing DLL. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
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RasDeleteEntry 


The RasDeleteEntry function deletes an entry from a phone book. 


Parameters 

loszPhonebook 
Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a phone book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog Dox. 


IpszEntry — 


Pointer to a null-terminated string containing the name of an existing entry to be 
deleted. 


Return Values 
If the function succeeds, the return value is ERROR_SUCCESS. 


‘If the function fails, the return value is ERROR_INVALID_ NAME. 


Remarks 


The following sample code deletes the phone book entry specified by the variable 
IpszEntry. 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Requires Windows 95 OSR2 or later. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Hn preenee as Unicode and ANSI versions on Windows NT/2000. 
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RasCreatePhonebookEntry, RasEnumEntries 


The RasDial function establishes a RAS connection between a RAS client and a RAS 
server. The connection data includes callback and user-authentication information. 
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IoRasDialParams 7 
Pointer to a RASDIALPARAMS structure that specifies calling parameters for the 
RAS connection. 


The caller must set the RASDIALPARAMS structure’s dwSize member to 
sizeof(RASDIALPARAMS) to identify the version of the structure being passed. 


dwNotifierType 
_ Specifies the nature of the /ovNotifier parameter. If jovNotifier is NULL, dwNotifierType 
is ignored. If JovNotifier is not NULL, set dwNotifierType to one of the following values. 


Value Meaning 


OxFFFFFFFF _ The /pvNotifier parameter is a handle to a window to receive 
progress notification messages. In a progress notification message, 
wParam is the equivalent of the rasconnstate parameter of 
RasDialFunc and RasDialFunct1, and /Param is the equivalent of 
the dwError parameter of RasDialFunc and RasDialFunct1. 


The progress notification message uses a system registered 
message code. You can obtain the value of pe message code as 
follows: 7 : 


0 The /pvNotifier parameter points to a RasDialFunc callback function. 

1 The /pvNotifier parameter points to a pase une callback 
function. 

2 _ Windows NT/2000: The /pvNotifier parameter points to a 


RasDialFunc2 callback function. 


IBUNOHOF. 
Specifies a window handle ora RasDialFunc, RasDialFunct, or RasDialFunc2 
callback function to receive RasDial event notifications. The dwNotifierT ype 
parameter specifies the nature of /ovNotifier. Please refer to its description preceding 
for further detail. 


If this parameter is not NULL, RasDial sends the window a message, or calls the 
callback function, for each RasDial event. Additionally, the RasDial call operates 
asynchronously: RasDial returns immediately, before the connection is established, 
and communicates its progress via the window or callback function. 


If JovNotifier is NULL, the RasDial call operates synchronously: RasDial does not 
return until the connection attempt has completed successfully or failed. | 
If JovNotifier is not NULL, notifications to the window or callback function can occur at | 


any time after the initial call to RasDial. Notifications end when one of the following 
events occurs. 
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e The connection is established. In other words, the RAS connection state is 
RASCS_Connected. 


e The connection fails. In other words, dwError is nonzero. 
-@ RasHangUp is called on the connection. 


The callback notifications are made in the context of a thread captured during the 
initial call to RasDial. 

IphRasConn 
Pointer to a variable of type HRASCONN. You must set the HRASCONN variable to 
NULL before calling RasDial. If RasDial succeeds, it stores a handle to the RAS 
connection into “/ohRasConn. 


Return Values | 
If the function succeeds, the immediate return value is zero. In addition, the function 
stores a handle to the RAS connection into the variable pointed to by JohRasConn. 


If the function fails, the immediate return value is a nonzero error value, either from the 
set listed i in 1 the RAS header file or ERROR __ NOT_ ENOUGH_ MEMORY. 


Remarks 
Errors that occur after the immediate return can be detected by RasGetConnectStatus. 
Data is available until an application calls RasHangUp to hang up the connection. 


An application must eventually call RasHangUp whenever a non-NULL connection 
handle is stored into */ohRasConn. This applies even if RasDial returns a nonzero 
(error) value. 


An application can safely call RasHangUp from a RasDial notifier callback function. If 


__ this is done, however, the hang-up does not occur until the routine returns. 


Windows NT/2000: If the structure pointed to by /JoRasDialExtensions enables 
RDEOPT_PausedStates, the RasDial function pauses whenever it enters a state in 
which the RASCS_PAUSED bit is set to one. To restart RasDial from such a paused 
state, call RasDial again, passing the connection handle returned from the original — 
RasDial call in *JohRasConn. The same notifier used in the original RasDial call must be 
used when restarting from a paused state. 


Windows 2000: RAS supports referenced connections. If the entry being dialed is 
already connected, RasDial will return SUCCESS and the connection will be referenced. 
To disconnect the connection, each RasDial on the connection should be matenee bya 
RasHangUp. 


Windows 2000: Because some phone book entries require Extensible Authentication 
Protocol (EAP) for authentication, the caller should call RasGetEapUserldentity before 
calling RasDial. lf RasGetEapUserldentity returns 
ERROR_INVALID_ENTRY_FOR_FUNCTION, the phone book entry does not require 
EAP. However, if RasGetEapUserldentity returns NO_ERROR, the caller should copy 
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the EAP identity information from RasGetEapUserldentity into the RasEapinfo member 
of RASDIALEXTENSIONS, and the szUserName member of RASDIALPARAMS. See 
RasGetEapUserldentity for more information. If the phone book entry requires EAP, the 
dwfOptions member of the RASENTRY structure for the entry contains the 
RASEO_RequireEAP flag. 


To specify that RasDial should enter a RASCS_CallbackSetByCaller state, set 
lpRasDialParams->szCallbackNumber to “*” on the initial call to RasDial. When your 
notification handler is called with this state, you can set the callback number to a number 
supplied by the user. 


Windows 95: Windows 95 does not support the RASCS_CallbackSetByCaller state or — 
any of the other paused states. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
~ Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 
Library: Use Rasapi32.lib. 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, Dialable 
Addresses, RasDialDlg, RasDialFunc, RasDialFunc1, RasDialFunc2, 


RasGetConnectStatus, RasHangUp, RASDIALEXTENSIONS, RASDIALPARAMS, 
WM_RASDIALEVENT 


-RasDialDlig — 


The RasDialDlg function establishes a RAS connection using a specified phone book 
entry and the credentials of the logged-on user. The function displays a stream of dialog 
boxes that indicate the state of the connection operation. | . | 


SERS 
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Parameters 


lpszPhonebook 
Pointer to a null-terminated string that specifies the full path and file name ofa Phone 
Book (PBK) file. If this parameter is NULL, the function uses the current default phone 
book file. The default phone book file is the one selected by the user in the User 
Preferences property sheet of the Dial-Up Networking dialog box. 


loszEntry 
Pointer to a null-terminated string that contains the name of the phone book entry to 
dial. 


loszPhoneNumber 
Pointer to a null-terminated string that contains a phone number that overrides the 
- numbers stored in the phone book entry. If this parameter is NULL, RasDialDlg uses 
the numbers in the phone book entry. 


loInfo 
Pointer to a RASDIALDLG structure that contains additional inout and output 
parameters. On input, the dwSize member of this structure must specify 
sizeof(RASDIALDLG). If an error occurs, the dwError member returns an error code; | 
otherwise, it returns zero. 


Return Values 
If the function establishes a RAS connection, the return value is a nonzero value. 


If an error occurs, or if the user selects the Cancel button during the dialing operation, 
the return value is zero. If an error occurs, the dwError member of the RASDIALDLG 
structure returns a nonzero system or RAS error code. 


Remarks 


The RasDialDlg function displays a series of dialog boxes that are similar to the dialog 
boxes that main Dial-Up Networking dialog box displays when the user selects the Dial 
button. The RasDialDlg function is useful for applications in which you want to display a 
standard user interface for a connection operation without presenting the main phone 
book dialog box. For example, the RAS AutoDial service uses this function to establish a 
connection using the phone book entry associated with a remote address. 


The RasDialDlg function displays dialog boxes during the connection operation to 
provide feedback to the user about the progress of the operation. For example, the 
dialog boxes might indicate when the operation is dialing, when it is authenticating the 
user’s credentials on the remote server, and so on. The dialog boxes also provide a_ 
Cancel button for the user to terminate the operation. 


RasDialDlg returns when the connection is established, or when the user cancels the 
operation. 


The sample code on the following page dials the entry in the default phone book 
specified by the variable /pszEntry. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 

Header: Declared in Rasdig.h. 

Library: Use Rasdlg.lib. 


Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. — 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
_ RASDIALDLG, RasPhonebookDig | 


RasDialFunc | 


The RasDialFunc function is an application-defined or library-defined callback function 


that the RasDial function calls when a change of state occurs during a RAS connection 
process. 
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Parameters 


unMsg 
Specifies the type of event that has occurred. Currently, the only event defined is 
WM_RASDIALEVENT. 


rasconnstate_ . 
Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial 
remote access connection process is about to enter. 


dwError 
Specifies the error that has occurred, or zero if no error has occurred. 


RasDial calls RasDialFunc with dwError set to zero upon entry to each connection 
state. If an error occurs within a state, RasDialFunc is called again with a nonzero 
dwError value. 


Return Values 
None. 


Remarks 


A RasDial connection operation is suspended during a call to a RasDialFunc callback 
function. For that reason, your RasDialFunc implementation should generally return as 
quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices 
such as modems often have time-out periods measured in seconds rather than 
milliseconds; a slow return from a RasDialFunc function is generally not a problem. The 
prompt return requirement also does not apply when dwError is nonzero, indicating that — 
an error has occurred. It is safe, for example, to put up an error dialog box and wait for 
user input. 


Your RasDialFunc implementation should not depend on the order or occurrence of 
particular RASCONNSTATE connection states, because this may vary between 
platforms. 


Do not call the RasDial function from within a RasDialFunc callback function. You can 
call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, 
RasGetErrorString, and RasHangUp functions from within the callback function. For 
example, calling RasGetConnectStatus from within a callback function would be useful 
for determining the name and type of the connecting device. 


Note For convenience, RasHangUp can be called from within a RasDialFunc callback 
function. However, much of the hang-up processing occurs after the RasDialFunce 
callback function has returned. 


RasDialFunc i is a placeholder for the piuweud -defined or ibrary- -defined function 
name. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASCONNSTATE, RasDial, RasDialFunc1, RasDialFunc2, RasEnumConnections, 
RasEnumeEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp 


RasDialFunc1 


A RasDialFunc1 function is an application-defined or library-defined callback function 
that the RasDial function calls when a change of state occurs during a remote access 
connection process. A RasDialFunci1 function is comparable to a RasDialFunc 
function, but is enhanced by the addition of two parameters: a handle to the RAS 
connection, and an extended error code. 


Parameters 


hrasconn | | 
Handle to the RAS connection, as returned by RasDial. 


unMsg | 


Specifies the type of event that has occurred. Currently, the only event defined is 
WM_RASDIALEVENT. | 


rascs 


Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial 
remote access connection process is about to enter. 
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QwError 
Specifies the error that has occurred. If no error has occurred, dwError is zero. 
RasDial calls RasDialFunc1 with dwError set to zero upon entry to each connection 
state. If an error occurs within a state, RasDial calls RasDialFunc1 again with a 
nonzero dwError value. 


In some error cases, the dwExtendedError parameter contains extended error 
information. | 

dwExtendedError | 
Specifies extended error information for certain nonzero values of dwError. For all 
other values of dwError, dwExtendedError is zero. 


The contents of dwExtendedError are defined for values of dwError as follows. 


dwError | dwExtendedError 
ERROR_SERVER_NOT_RESPONDING _ Specifies the NetBIOS error that 
occurred. | 

ERROR_NETBIOS_ERROR Specifies the NetBIOS error that 

| occurred. | 
ERROR_AUTH_INTERNAL Specifies an internal diagnostics code. 

~ERROR_CANNOT_GET_LANA Specifies a routing error code, which is a 
| RAS error. 


Return Values 


None. 


Remarks 


A RasDial connection operation is sisponded during acalltoa RasDialFunct callback 
function. For that reason, your RasDialFunc1 implementation should generally return as 
quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices 
such as modems often have time-out periods measured in seconds rather than 
milliseconds; a slow return from a RasDialFunci1 function is generally not a problem. 
The prompt return requirement also does not apply when dwError is nonzero, indicating 


_ that an error has occurred. It is safe, for ee to put up an error dialog box and wait 


for user input. 


Your RasDialFunc1 implementation should not depend on the order or occurrence of 
particular RASCONNSTATE connection states, because this may vary between 
platforms. 


Do not call the RasDial function from within a RasDialFunc1 callback function. You can 
call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, 
RasGetErrorString, and RasHangUp functions from within the callback function. For 
example, calling RasGetConnectStatus from within a callback function would be useful 
for determining the name and type of the connecting device. _ 
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Note that, for convenience, RasHangUp can be called from within a RasDialFunct 
callback function. However, much of the hang- up processing occurs after the 
RasDialFunci callback function has returned. 


RasDialFunct1 is a placeholder for the application-defined or library-defined function 
name. | 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
_ Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, 
RasDialFunc, RasDialFunc2, RASCONNSTATE, RasEnumConnections, 
RasEnumeEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp 


RasDialFunc2 


A RasDialFunc2 function is an application-defined or library-defined callback function 
that the RasDial function calls when a change of state occurs during a remote access © 
connection process. A RasDialFunc2 function is similar to the RasDialFunct callback 
function, except that it provides additional information for multilink connections. 


Parameters 


dwCallbackld 
Provides an application-defined value that was specified in the dwCallbacklid 
member of the RASDIALPARAMS structure passed to RasDial. 
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| dwSubEntry 


Specifies a subentry index for the phone book entry associated with this connection. 


This value indicates the subentry that generated this call to your RasDialFunc2 
callback function. 7 


hrasconn 
Handle to the RAS connection, as returned by RasDial. 
unMsg | 


Specifies the type of event that has occurred. Currently, the only event defined is 
WM_RASDIALEVENT. 


rascs 


Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial 
remote access connection process is about to enter. | 


dwError | | 
Specifies the error that has occurred. If no error has occurred, dwError is zero. 


The RasDial function calls RasDialFunc2 with dwError set to zero upon entry to each 


connection state. If an error occurs within a state, RasDial calls RasDialFunc2 again 
with a nonzero dwError value. 


In some error cases, the dwExtendedError parameter contains extended error 
information. 


dwExtendedError 


Specifies extended error information for certain nonzero values of dwError. For all 
other values of dwError, dwExtendedError is zero. 


The contents of dwExtendedError are defined for values of dwError as follows. 


dwError dwExtendedError 
ERROR_SERVER_NOT_RESPONDING _ Specifies the NetBIOS error that 
| occurred. 

ERROR_NETBIOS_ERROR Specifies the NetBIOS error that 

| -_ occurred. 
ERROR_AUTH_INTERNAL Specifies an internal diagnostics code. 
ERROR_CANNOT_GET_LANA Specifies a routing error code, which is a 

7 RAS error. | 


Return Values 
lf the RasDialFunc2 function returns a nonzero value, RasDial continues to send 
callback notifications. 


lf the RasDialFunc2 function returns zero, RasDial stops sending callback notifications 
for all subentries. 
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Remarks 


A RasDial connection operation is suspended during a call toa RasDialFunc2 callback 
function. For that reason, your RasDialFunc2 implementation should generally return as 
quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices 
such as modems often have time-out periods measured in seconds rather than 

milliseconds; a slow return from a RasDialFunc2 function is generally not a problem. 
The prompt return requirement also does not apply when dweError is nonzero, indicating 
that an error has occurred. It is safe, for example, to put up an error dialog box and wait 
for user input. 


Your RasDialFunc2 implementation should not depend on the order or occurrence of 
particular RASCONNSTATE connection states, because this may vary between 
platforms. 


Do not call the RasDial function from within a RasDialFunc2 callback function. You can 
call the RasGetConnectStatus, RasEnumEntries, RasEnumConnections, 
RasGetErrorString, and RasHangUp functions from within the callback function. For 
example, calling RasGetConnectStatus from within a callback function would be useful 
for determining the name and type of the connecting device. 


Note For convenience, RasHangUp can be called from within a RasDialFunc2 
callback function. However, much of the hang-up processing occurs after the 
RasDialFunc2 callback function has returned. 


RasDialFunca2 is a piacenoel for the application- -defined or rely eed 
function name. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


‘Remote Access Service (RAS) Overview, Remote Access Service Functions: RasDial, 
RasDialFunc, RasDialFunc1, RASCONNSTATE, RasEnumConnections, 
RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp 


RasEditPhonebookEntry — 


The RasEditPhonebookEntry function edits an existing phone book entry. The function — 
displays a dialog box in which the user can modify the existing information. 


~Windows NT/2000: The RasEditPhonebookEntry function calls the RasEntryDig 
function. Applications written for Windows NT version 4.0 should use RasEntryDlg. 
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Parameters 


hwnd 
Handle to the parent window of the dialog box. 


| szPhonebook —_ 
| Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a Phone Book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog box. 


Windows 95: Dial-up networking stores phone book entries in the registry rather than 
in a phone book file. 


lpszEntryName 


Pointer to a null-terminated string that specifies the name of an existing entry in the 
phone book file. | | | 


Return Values - | 
If the function succeeds, the return value is zero. 


If the function fails, the return value can be one of the following error codes. 


Value | Description 3 
~ ERROR_BUFFER_INVALID | The phone book entry buffer is invalid. 
ERROR_CANNOT_OPEN_PHONEBOOK _ The phone book is corrupted or missing 
components. 


ERROR_CANNOT_FIND_PHONEBO 
ENTRY a 


The phone book entry does not exist. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. — 
Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. | | 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasCreatePhonebookEntry, RasEntryDlg, RasGetEntryDialParams, 
RasSetEntryDialParams 


RasEntryDlg 


The RasEntryDlg function displays modal property sheets that allow a user to 
manipulate phone book entries. If editing or copying an existing phone book eniry, the 
function displays a phone book entry property sheet. The RasEntryDlg function returns 
when the user closes the property sheet. 


Parameters 


lpszPhonebook 
Pointer to a null-terminated string that specifies the full path and file name of a phone 
book (PBK) file. If this parameter is NULL, the function uses the current default phone 
book file. The default phone book file is the one selected by the user in the User 
Preferences property sheet of the Dial-Up Networking dialog BO 


loszEntry 
Pointer to a null-terminated string that contains the name of the oe book entry to 
edit, copy, or create. 


If you are editing or copying an entry, this parameter is the name of an existing phone 
book entry. If you are copying an entry, set the RASEDFLAG —CloneEntry flag in the 
dwFlags member of the RASENTRYDLG structure. 


If you are creating an entry, this parameter is a default new entry name that the user 

~ can change. If this parameter is NULL, the function provides a default name. If you © 
are creating an entry, set the RASEDFLAG_NewEntry flag in the dwFlags member of 
the RASENTRYDLG structure. 


“Ipinto 
Pointer to a RASENTRYDLG structure that contains additional input and output 
parameters. On input, the dwSize member of this structure must specify | 
sizeof(RASENTRYDLG). Use the dwFlags member to indicate whether you are 
creating, editing, or copying an entry. If an error occurs, the dwError member returns 
an error code; otherwise, it returns zero. 
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RasEnumAutodialAddresses 


The RasEnumAutodialAddresses function returns a list of all addresses in the AutoDial 
mapping database. 


Parameters 


lppAddresses | 
Pointer to an array of string pointers, with additional space for the storage of the 
strings themselves at the end of the buffer. Each string is the name of an address in 
the AutoDial mapping database. . o. 


lf IppAddresses is NULL, RasEnumAutodialAddresses sets the JodwcbAddresses 
and lpdwcAddresses parameters to indicate the required size, in bytes, and the 
number of address entries in the database. 


IpdwcbAddresses | 
Pointer to a variable that contains the size, in bytes, of the buffer specified by the 
IppAddresses parameter. On return, the function sets this variable to the number of 
bytes returned, or the number of bytes required if the buffer is too small. | 


lodwcAddresses 
Pointer to a variable that receives the number of address strings returned in the 
lppAddresses buffer. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is the following error code. 
Value | Meaning | 


~ERROR_INVALID_PARAMETER NULL was passed for the IpdwcbAddresses or | 
| lpdwcAddresses parameter. | 
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Windows NT 4.0 or later. 
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Unsupported. 
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Windows 95/98 


Header: Declared in Ras.h. 


Library 


Use Rasapi32.lib. 
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lons on 


Unicode 


Implemented as Unicode and ANSI vers 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 


RASAUTODIALENTRY, RasGetAutodialAddress, RasSetAutodialAddress 


RasEnumConnections 


The RasEnumConnections function lists all active RAS connections. It returns each 


connection’s handle and phone book entry name. 
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Pointer to a buffer that receives an array of RASCONN structures, one for each RAS 
connection. Before calling the function, an application must set the dwSize member of 
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RasEnumDevices 


The RasEnumDevices function returns the name and type of all available RAS-capable 


devices. 
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Parameters 


lpRasDevinfo . 
Pointer to a buffer that receives an array of RASDEVINFO structures, one for each © 
RAS-capable device. Before calling the function, set the dwSize member of the first 
RASDEVINFO structure in the buffer to sizeof(RASDEVINFO) to identify the version of 
the structure. — | | 


lpcb. 
Pointer to a variable that contains the size, in bytes, of the JoRasDevinfo buffer. On 
return, the function sets this variable to the number of bytes required to enumerate the 
devices. 


To determine the required buffer size, call RasEnumDevices with the JoRasDevinfo 
parameter set to NULL and the variable pointed to by /pcb set to zero. The function 
returns the required buffer size in the variable pointed to by /pcb. (See sample code 
under Remarks section.) 


lpcDevices 
Pointer to a variable that the function sets to the number of RASDEVINFO structures 
written to the jJoRasDevinfo bufter. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is a nonzero RAS error value or one of following 
error codes. 


Value | Meaning 


ERROR_BUFFER_TOO_SMALL The /oRasDevinfo buffer is not large enough. 
The function returns the required buffer size in 
7 | , the variable pointed to by /pcb. 


ERROR_NOT_ENOUGH_MEMORY __ Indicates insufficient memory. 
ERROR_INVALID_PARAMETER Indicates an invalid parameter value. 


ERROR_INVALID_USER_BUFFER _ The address or buffer specified by JoRasDevinfo © 
is invalid. 
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The following sample code enumerates the devices on the current machine. The code 
initially calls RasEnumDevices with a |pRasDevinfo parameter of NULL, to obtain the 


Remarks 


SIZE O 


f the buffer that should be passed in. The code also sets the dwSize member of 
the first RASDEVINFO structure to sizeof(RASDEVINFO) to specify the version of the 


structure. 
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RasEnumeEntries 


The RasEnumEntries function lists all entry names in a remote access phone book. 
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(continued) 


Parameters 


reserved | . °8 
Reserved; must be NULL. 


lposzPhonebook 
Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a Phone Book (PBk) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
| user in the User Preferences property sheet of the Dial-Up Networking dialog box. 


Windows 2000: If this parameter is NULL, the entries are enumerated from all the 
remote access phone book files in the AllUsers profile and the user’s profile. 


Windows 95: This parameter is ignored. Dial-up networking stores phone book 
entries in the registry rather than in a phone book file. 


lprasentryname 2 
Pointer to a buffer that receives an array of RASENTRYNAME structures, one for 
each phone book entry. Before calling the function, an application must set the 
dwSize member of the first RASENTRYNAME structure in the buffer to 
sizeof(RASENTRYNAME) in order to identify the version of the structure being 
passed. 


lpcb | | | 
Pointer to a variable that contains the size, in bytes, of the buffer specified by 
lprasentryname. On return, the function sets this variable to the number of bytes 
required to successfully complete the call. 


locEntries | | | 
Pointer to a variable that the function, if successful, sets to the number of phone book 
entries written to the buffer specified by /orasentryname. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is a nonzero error value listed in the RAS header file 
or one of the following values. 
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Value Meaning 


ERROR_BUFFER_TOO____ The buffer pointed to by the /prasentryname parameter is 
SMALL | not large enough to hold all the entries. 


ERROR_INVALID_SIZE The value of dwSize in the RASENTRYNAME structure 
pointed to by /prasentryname, specifies a version of the 
structure that is not supported on the current platform. For 
example, on Windows 95, RasEnumEntries returns this 
error if dwSize indicates that RASENTRYNAME includes 
the dwFlags and szPhonebookPath members, since 
these members are not supported on Windows 95 (they 
are supported only on Windows 2000 and later). . 


ERROR_NOT_ENOUGH___ The function could not allocate sufficient memory to 
MEMORY complete the operation. | 


Remarks 


The following sample code enumerates the RAS phone book entries on the current 
machine. The code initially calls RasEnumEntries to obtain the size of the buffer to pass 
in. The code then calls RasEnumEntries again, to enumerate the entries. Note that for 
both calls, the code sets the dwSize member of the first RASENTRY structure in the 
buffer to sizeof(RASENTRY) to specify the structure version. 


continued) 
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(continued) 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 

Library: Use Rasapi32. lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASENTRYNAME, RasEnumConnections 


RasFreeEapUserldentity 


Use the RasFreeEapUserldentity function to free the memory buffer returned by 
RasGetEapUserldentity. | 


arameters 


pRasEapUserldentity © 


Pointer to the RASEAPUSERIDENTITY structure returned by the 
RasGetEapUserldenity function. 


Return Values 
If the function succeeds, the return value is NO_ERROR. 


Otherwise, the function returns one of the following error codes. 


Remarks 


RasFreeEapUserldentity may be called with the pRasEapUserldentity parameter equal 
to NULL. 
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Windows NT/2000: Requires Windows 2000. 

Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows 2000. 


RASEAPUSERIDENTITY, RasGetEapUserldentity 


RasGetAutodialAddress 


The RasGetAutodialAddress function retrieves information about all the AutoDial 
entries associated with a network address in the AutoDial mapping database. 


Parameters 


lpszAdadress 
Pointer to a null-terminated string that specifies the address for which information is 
requested. This can be an IP address, Internet host name (“www.microsoft.com’), or. 
NetBIOS name (“products1”). eg ioe 

_lpdwReserved 

Reserved; must be NULL. 

IpAutoDialEntries 
Pointer to a buffer that receives an array of RASAUTODIALENTRY structures, one 
for each AutoDial entry associated with the address specified by the /pszAddress 
parameter. Before calling RasGetAutodialAddress, set the dwSize member of the 


first RASAUTODIALENTRY structure in the buffer to sizeof (RASAUTODIALENTRY ) to 
identify the version of the structure. 


144 


Volume 4 Remote Access Services 


‘If IpAutoDialEntries is NULL, RasGetAutodialAddress sets the 
lodwebAutoDialEntries and |pdwcAutoDialEntries parameters to indicate the required 
buffer size, in bytes, and the number of AutoDial entries. 

lpodwcbAutoDialEntries 
Pointer to a variable that contains the size, in bytes, of the /oAutoDialEntries buffer. 

On return, the function sets this variable to the number of bytes returned, or the 

number of bytes required if the buffer is too small. 

lpdwcAutoDialEntries 
Pointer to a variable that receives the number of structure elements returned in the 
loAutoDialEntries buffer. 


Return Values. 
lf the function succeeds, the return value Is zero. 


If the function fails, the return value is one of the following error codes. 


Value Meaning 

ERROR_XXX_NOT_FOUND _ The address was not found in the mapping database. 

ERROR_INVALID_SIZE The dwSize member of the RASAUTODIALENTRY 
structure is an invalid value. 

ERROR_INVALID_ | The /IpszAddress, lodwcbAutoDialEntries, or 

PARAMETER | IpdwcAutoDialEntries parameter was NULL. 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASAUTODIALENTRY, RasEnumAutodialAddresses, RasSetAutodialAddress 


RasGetAutodialEnable 


The RasGetAutodialEnable function indicates whether the AutoDial feature is enabled 
for a specified TAPI dialing location. For more information about TAPI dialing locations, 
see the TAP! Programmer’s Reference in the Platform SDK. 
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Parameters 


dwDialingLocation 
Specifies the identifier of a TAPI dialing location. 
IpfEnabled | 


Pointer to a BOOL variable that receives a nonzero value if AutoDial is enabled for the 
specified dialing location, or zero if it is not enabled. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is a nonzero value. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
7 Header: Declared in Ras.h. 


Library: Use Rasapi32.lib. . : 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service RAS) Overview, Remote Access Service Functions, 
RasSetAutodialEnable | 


RasGetAutodialParam 


The RasGetAutodialParam function retrieves the value of an AutoDial parameter. 
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Parameters 
oy 


following values. 
Value 


RASADP__ 
DisableConnectionQuery 


RASADP_ 
LoginSessionDisable 


RASADP __ 
SavedAddressesLimit 


~ RASADP._ 
FailedConnectionTimeout 


RASADP_ 


ConnectionQueryTimeout 


Specifies the AutoDial parameter to retrieve. This parameter can be one of the 


Meaning 


The /pvValue parameter returns a DWORD value. If this 
value is zero (the default), AutoDial displays a dialog box 
to query the user before creating a connection. If this 
value is 1, and the AutoDial database has the phone 
book entry to dial, AutoDial creates a connection without 
displaying the dialog box. 


The /pvValue parameter returns a DWORD value. If this 
value is 1, the system disables all AutoDial connections 
for the current logon session. If this value is zero (the 
default), AutoDial connections are enabled. The 
AutoDial system service changes this value to zero 


~ when a new user logs on to the workstation. 


The /pvValue parameter returns a DWORD value that 
indicates the maximum number of addresses that 
AutoDial stores in the registry. AutoDial first stores 
addresses that it used to create an AutoDial connection; 
then it stores addresses that it learned after a RAS 
connection was created. Addresses written using the 
RasSetAutodialAddress function are always saved, 
and are not included in calculating the limit. The default 
value is 100. 


The IovValue parameter returns a DWORD value that 
indicates a time-out value, in seconds. When an 


- AutoDial connection attempt fails, the AutoDial system 


service disables subsequent attempts to reach the same 
address for the time-out period. This prevents AutoDial 
from displaying multiple connection dialog boxes for the 
same logical request by an sa clair The default 
value is 5. 


The IpvValue parameter points to a DWORD value that — 
indicates a time-out value, in seconds. Before attempting | 
an AutoDial connection, the system will display a dialog 
asking the user to confirm that the system should dial. 


_The dialog has a countdown timer that will terminate the 


dialog with a “Do not dial” selection if the user takes no 


~ action. The DWORD value pointed to by /pvValue 
_ specifies the initial time on this countdown timer. 
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lpvValue 
Pointer to a buffer that receives the value for the specified parameter. 


lpdwcbValue 


Pointer to a DWORD value. On input, set this value to indicate the size, in bytes, of 


the /pvValue buffer. On output, this value indicates the actual size of the value written 
to the buffer. | 


Return Values 
If the function succeeds, the return value is zero. 


lf the function fails, the return value can be one of the following error codes. 


Value Meaning 
ERROR_INVALID_PARAMETER _ The dwKey or IpvValue parameter is invalid. 
ERROR_INVALID_SIZE The size specified by the odwcbValue is too small. 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Unsupported. | | 

Header: Declared in Ras.h. , 7 qe 
Library: Use Rasapi32.lib. 


Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


~ Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasSetAutodialAddress, RasSetAutodialParam | 


RasGetConnectionStatistics 


The RasGetConnectionStatistics function retrieves accumulated connection statistics. 
for the specified connection. 


Parameters 


hRasConn, 


Handle to the connection. Use RasDial or RasEnumConnections to obtain this 
handle. Se a, 
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Ip Statistics 
Pointer to a RAS_ STATS structure to receive the statistics. Set the dwSize member 
of this structure to sizeof(RAS_STATS) before calling RasGetConnectionStatistics. 
This parameter cannot be NULL. 


Return Values 
lf the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value is one of the following error codes. 
Value Meaning 


E_INVALID_ARG At least one of the following is true: the hRasConn 
parameter is zero, the /pStatistics parameter is NULL, or 
the value specified by the dwSize member of the 
RAS_STATS structure specifies a version of the structure 
that is not supported by the operating system in use. 7 


ERROR_NOT_ENOUGH___ The function could not allocate sufficient memory to 
MEMORY complete the operation. 


Other | Use FormatMessage to retrieve the system error 


message that corresponds to the error code returned. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasClearConnectionStatistics, RasDial, nAsEnumMeennectone, 
RasGetLinkStatistics 


RasGetConnectStatus 


The RasGetConnectStatus function retrieves information on the current status of the 
specified remote access connection. An application can use this call to determine when 
an asynchronous RasDial call is complete. 


Chapter 7 RAS Functions 149 


Parameters 

hrasconn 
Specifies the remote access connection for which to retrieve the status. This handle 
must have been obtained from RasDial or RasEnumConnections. 

Iprasconnstatus | 
Pointer to a RASCONNSTATUS structure that the function fills with status 
information. Before calling the function, an application must set the dwSize member 
of the structure to sizeof(RASCONNSTATUS) in order to identify the version of the 
structure being passed. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is a nonzero error value listed in the RAS header file | 
or either ERROR _BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY. 


Remarks 
The return value for RasGetConnectStatus is not necessarily equal to the value of the 
dwError member of the RASCONNSTATUS structure returned by 
RasGetConnectStatus. The return value of RasGetConnectStatus indicates errors 
that occur during the RasGetConnectStatus function call, whereas the dwError 

~ member indicates errors that prevented the connection from being established. 


Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASCONNSTATUS, RasDial, RasEnumConnections 7 


RasGetCountryinfo 


The RasGetCouniryInfo function retrieves country- specific dialing information from the 
Windows Telephony list of countries. 
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For more information about country-specific dialing information and Telephony 
Application Programming Interface (TAPI) country identifiers, see ine TAP! portion of the 
Platform SDK. 


Parameters 
lpRasCtryinfo 
Pointer to a RASCTRYINFO structure that receives the country- specific dialing 
information followed by additional bytes for a country description string. Before calling 
the function, set the dwSize member of the structure to sizeof (RASCTRYINFO) to 
. identify the version of the structure. You must also set the dwCountryld member to 
the TAPI country identifier of the country for which to get information. 


The size of the buffer should be at least 256 bytes. 
IpdwSize 
Pointer to a variable that contains the size, in bytes, of the buffer pointed to by the 


|pDRasCtryInfo parameter. On return, the function sets this variable to the number of 
ae ie 


Return Values | 
If the function succeeds, the return value is zero. 


If the function fails, the return value can be one of the following error codes. 


Value | Meaning 
ERROR_INVALID_USER_BUFFER _ The address or buffer specified by IoRasCtryInfo 
is invalid. 


ERROR_INVALID_PARAMETER The dwCountryld member of the structure 
| pointed to by ipRasCirylnto was not a valid 
value. 


ERROR_BUFFER_TOO_SMALL The size of the IpRasCtryinfo buffer specified by 
| | the IpdwSize parameter was not large enough to 
store the information for the country identified by 
the dwCountryld member. The function returns 
the required buffer size in the variable pointed to 
— | by IpdwSize. | | 
ERROR_TAPI_CONFIGURATION TAPI subsystem information was corrupted. 
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Remarks 


To enumerate information for all countries in the Windows Telephony list, set the 
dwCountryld member of the RASCTRYINFO structure to 1 in the initial 
RasGetCountryInfo call. This causes the function to return information for the first 
country in the list. The value returned in the dwNextCountryld member is the country 
identifier of the next country in the list. Use this value in repeated calls to 
RasGetCountryInfo until dwNextCountrylD returns zero, indicating the last country in 
the list. 


on 


i 


pantataatanas: 
3 


Windows NT/2000: Requires Windows NT 4.0 or later. 
7 Windows 95/98: Requires Windows 95 OSR2 or later. 
Header: Declared in Ras.h. 
Library: Use Rasapi32.lib. | | | 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASCTRYINFO | 


~RasGetCredentials 


The RasGetCredentials function retrieves the user credentials associated with a 
specified RAS phone book entry. © 


Parameters — 
lpszPhonebook — oo | sey | 
Pointer to a null-terminated string that specifies the full path and file name of a phone 
book (PBK) file. If this parameter is NULL, the function uses the current default phone 
book file. The default phone book file is the one selected by the user in the User 
Preferences property sheet of the Dial-Up Networking dialog box. - 
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IpszEntry | 
Pointer to a null-terminated string that contains the name of a phone book entry. 
lpCredentials 
Pointer to a RASCREDENTIALS structure that receives the user credentials 
associated with the specified phone book entry. Before calling RasGetCredentials, 
set the dwSize member of the structure to sizeof (RASCREDENTIALS), and set the 
dwMask member to indicate the credential information to retrieve. When the function 
returns, dwMask indicates the members that were successfully retrieved. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is one of the following error codes. 


Value _ Meaning | 
ERROR_CANNOT_OPEN_PHONEBOOK _ The specified phone book cannot be 
found. | 
ERROR_CANNOT_FIND_PHONEBOOK___ The specified entry does not exist in the 
ENTRY phone book. 
ERROR_INVALID_PARAMETER The /pCredentials parameter was NULL. 
ERROR_INVALID_ SIZE | | ~The dwSize member of the 


RASCREDENTIALS structure is an 
unrecognized value. 


Remarks 


The RasGetCredentials function retrieves the credentials of the last user in order to 
connect using the specified phone book entry, or the credentials subsequently specified 
in a call to the RasSetCredentials function for the phone book entry. 


The RasGetCredentials function retrieves the user credentials that are stored securely 
for the specified phone book entry. This function is the preferred way of securely 
retrieving the credentials associated with a RAS phone book entry. RasGetCredentials 
supersedes the RasGetEntryDialParams function, which may not be supported in 
future releases of Windows 2000. 


Windows 2000 and later versions: RasGetCredentials does not return the actual 
password. Instead, the szPassword member of the RASCREDENTIALS structure - 
contains a handle to the saved password. You can substitute this handle for the saved 
password in subsequent calls to RasSetCredentials and RasDial. When presented with 
this handle, RasDial will retrieve and use the saved password The value of this handle 
may change in future versions of the operating system; do not Beveiop code that 
depends on the contents or format of this value. 
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Windows 2000 and later versions: The dwMask member of RASCREDENTIALS 
contains the RASCM_Password flag if the system has saved a password for the 


specified entry. If the system has no password saved for this entry, dwMask does not 
contain RASCM_Password. 


The following sample code retrieves the credentials for the phone book entry with the 


name “mazy”: 7 | a | 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASCREDENTIALS, RasGetEntryDialParams, RasSetCredentials 


RasGetCustomAuthData : 


Use the RasGetCustomAuthData function to retrieve connection-specific authentication 
information. This information is not specific to a particular user. 


0 


Parameters 


pszPhonebook 


Pointer to a null-terminated string containing the full path of the phone book (PBK) file. 
If this parameter is NULL, the function will use the system phone book. 
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pszEntry 
Pointer to a null-terminated string containing an existing pain name. 
pbCustomAuthData 
Pointer to a buffer to receive the authentication data. The caller should allocate the 
memory for this buffer. If the buffer is not large enough, RasGetCustomAuthData will 
return ERROR_BUFFER_TOO_SMALL, and the pdwSizeofEapData parameter will | 
contain the required size. 


_ pdwSizeofCustomAuthData 


Pointer to a DWORD variable that contains the size of the buffer pointed to by the 
pbCustomAuthData parameter. 


Return Values 
If the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value is one of the following error codes. 


Value Meaning | 
E_INVALIDARG The pdwSizeofCustomAuthData parameter is NULL. 
ERROR_BUFFER_TOO_ The buffer pointed to by pbCustomAuthData is too small 
SMALL | to receive the data. The pdwSizeofCustomAuthData 


| contains the required size. 
ERROR_CANNOT_OPEN_ RasGetEapUserData was unable to open the specified 


PHONEBOOK ~ phone book file. | 
ERROR_CANNOT_FIND_ RasGetEapUserData was unable to find the specified 
PHONEBOOK_ENTRY entry in the phone book. 

Other | Use FormatMessage to retrieve the system error 


message that corresponds to the error code returned. 


Windows NT/2000: Requires Windows 2000. 

Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows 2000. 


RasGetEapUserData, RasSetCustomAuthData 
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RasGetEapUserData 


Use the RasGetEapUserData function to retrieve user-specific Extensible 
Authentication Protocol (EAP) information for the specified phone book entry. 


Parameters 

hToken 
Handle to a primary or impersonation access token that represents the user for which 
to retrieve data. This parameter can be NULL if the function is called from a process 
already running in the user’s context. 

pszPhonebook 
Pointer to a null-terminated string containing the full ath of the phone book (PBK) file. 
If this parameter is NULL, the function will use the system phone book. 

pszEntry 
Pointer to a null- terminated string containing a an existing entry name. 

pbEapData 
Pointer to a buffer to receive the retrieved EAP data for the user. The caller should 
allocate the memory for this buffer. If the buffer is not large enough, 
RasGetEapUserData will return ERROR_BUFFER_TOO_SMALL, and the 
_ pdwSizeofEapData parameter will contain the required size. 


pdwSizeofEapData 
Pointer to a DWORD variable that contains the size of the buffer ey to by the 
pbEapData parameter. 


Return Values ees | 
If the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value is one of the following error codes. 


Value © ne 7 Meaning 


E_INVALIDARG — neo The pdwSizeofEapData Saranieler is NULL. 


ERROR_BUFF ER_TOO_SMALL The buffer pointed to by pbEapDaia is too small to 
| | receive the data. The pdwSizeofEapData contains 
the required size. 
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(continued) 

Value | Meaning 

ERROR_CANNOT_OPEN_ RasGetEapUserData was unable to open the 

PHONEBOOK specified phone book file. 

ERROR_CANNOT_FIND_ -RasGetEapUserData was unable to find the 

PHONEBOOK_ENTRY specified entry in the phone book. 

Other Use FormatMessage to retrieve the system error 
message that corresponds to the error code 
returned. 


Windows NT/2000: Requires Windows 2000. 

Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows 2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasSetEapUserData, RASEAPINFO 


RasGetEapUserldentity 


The RasGetEapUserldentity function retrieves identity information for the current user. 
Use this information to call RasDial with a phone book entry that requires Extensible 
Authentication Protocol (EAP). 


Parameters 


pszPhonebook 
Pointer to a null-terminated string containing the full path of the phone book (PBK) file. 
If this parameter is NULL, the function will use the system phone book. 


pszEntry 
Pointer to a null-terminated string containing an existing entry name. 
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dwFlags 
Specifies zero or more of the following flags that qualify the authentication process. 
Flag Description | 
RASEAPF_ Specifies that the authentication protocol should not bring up a 
NonInteractive graphical user-interface. If this flag is not present, it is okay for 


the protocol to display a user interface. 
RASEAPF_Logon Specifies that the user data is obtained from Winlogon. 


RASEAPF_Preview Specifies that the user should be prompted for identity 
information before dialing. 


hwnd . 


Handle to the parent window for the UI dialog. If the flnvokeUI parameter is FALSE, 


then hwnd should be NULL. 
ppRasEapUserldentity 


Pointer to a pointer that, on successful return, points to a RASEAPUSERIDENTITY 

~ structure containing EAP user identity information. RasGetEapUserldentity will 
allocate the memory buffer for the RASEAPUSERIDENTITY structure. Free this 
memory by calling RasFreeEapUserldentity. 


Return Values 


If the function succeeds, the return value is NO_ERROR. 


Otherwise, the function will return one of the following error codes. 


Value 


E INVALID ARG 
‘ERROR_INTERACTIVE_MODE 


ERROR_INVALID_ FUNCTION 


_ FOR_ENTRY 


_ ERROR_RASMAN_CANNOT_ 
INITIALIZE 
Other 


Meaning 


The pebEapUserldentity parameter is NULL. 


The function was called with the 
RASEAPF_NoniInteractive flag. However, the 
authentication protocol must display a UI in order to 
obtain the required identity information from the user. 


Either the authentication method for this phone book 
entry is not EAP, or the authentication method is 
EAP but the protocol uses the standard Windows 
NT/Windows 2000 credentials dialog to obtain user 
identity information. In either case, the caller does 
not need to pass EAP identity information to - 
RasDial. | 


The Remote Access Service failed to initialize 
properly. 


- Use FormatMessage to retrieve the system error 


message that corresponds to the error code 
returned. 
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Remarks | | 

RasGetEapUserldentiy calls the RAS function RasGetEapUserData and the EAP 
function RasEapGetldentity. RasEapGetldentity is implemented by the authentication 
protocol. 


If the function succeeds, that is the return value is NO_ERROR, the caller should copy 
the EAP identity information from the structure pointed to by ppRasEapUserldentity to 
the RASDIALPARAMS and RASDIALEXTENSIONS structures used in the call to 
RasDial. The following sample code demonstrates how to copy the identity information: 


lf the remote access application being developed has a graphical user interface, the 
caller of RasGetEapUserldentity should not specify the RASEAPF_NonInteractive flag. 
If the application has a command-line user interface, the caller may want to specify the 
RASEAPF_NonInteractive flag to prevent the authentication protocol from displaying a 
graphical user interface. | 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. | 
Unicode: Implemented as Unicode and ANSI versions on Windows 2000. | 


RASEAPUSERIDENTITY, RasDial, RasEapGetldentity, RasFreeEapUserldentity, 
RasGetEapUserData, RasSetEapUserData 


RasGetEntryDialParams 


The RasGetEntryDialParams function retrieves the connection information saved by 
the last successful call to the RasDial or RasSetEntryDialParams function for a 


specified phone book entry. 
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Parameters 


loszPhonebook 
Windows NT/2000: Pointer to a null-terminated string that seatiee the full path and 
file name of a Phone Book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog box. 


Windows 95: Dial-up pS stores phone book entries in the registiy: rather than 
in a phone book file. 


lorasdialparams 
Pointer to a RASDIALPARAMS structure. On input, the dwSize member must specify 
the size of the RASDIALPARAMS structure, and the szEntryName member must 
specify a valid phone book entry. On output, the structure receives the connection 
parameters associated with the specified phone book entry. _ 


Note that the szPhoneNumber member of the structure does not receive the phone 
number associated with the phone book entry. To get the phone number associated 
with a phone book entry, call the RasGetEntryProperties function. 


Windows 2000 and later versions: RasGetEntryDialParams does not return the 
actual password. Instead, the szPassword member of the RASDIALPARAMS 
structure contains a handle to the saved password. You can substitute this handle for 
the saved password in subsequent calls to RasSetEntryDialParams and RasDial. 
When presented with this handle, RasDial will retrieve and use the saved password. 
_ The value of this handle may change in future versions of the operating system; do 
not develop code that depends on the contents or format of this value. 
- IpfPassword | 
Pointer to a flag that indicates whether the function retrieved the piReword: associated 
with the user name for the phone book entry. The function sets this flag to TRUE if the 
user’s password was returned in the szPassword member of the 2. BASDIALPARANS 
structure pointed to by Iprasdialparams. 
Windows 2000 and later: The IpfPassword parameter is TRUE if the evsicin has 
saved a password for the specified entry. If the system has no password saved for 
this sOny, IpfPassword | is FALSE. | 


Return Values | | 
If the function succeeds, the return value is zero. 


"If the function fails, the return value is one of the following error codes. 
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Value _ Description 

ERROR_BUFFER_INVALID The /prasdialparams or lpfPassword pointer is invalid, 
or the /prasdialparams buffer is invalid. 

ERROR_CANNOT_OPEN_ The phone book is corrupted or missing components. 

PHONEBOOK 

ERROR_CANNOT_FIND_ The phone book entry does not exist. 


PHONEBOOK_ENTRY 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 


Library: Use Rasapi32.lib. 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, 
RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, 
RasSetEntryDialParams 


RasGetEntryProperties 


The RasGetEntryProperties function retrieves the properties of a phone book entry. 
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Parameters 

lpszPhonebook 
Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a Phone Book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog box. 


_|pszEntry | 

Pointer to a null-terminated string containing an existing entry name. If you specify an 
empty string, “’, the function returns default values in the buffers pointed to by the 
lpRasEntry and lpbDevicel/nfo parameters. 


lpRasEntry 
Pointer to a RASENTRY structure followed by additional bytes for the alternate phone 
number list, if there is one. The structure receives the connection data associated with 
the phone book entry specified by the JoszEntry parameter. Before calling the 
function, set the dwSize member of the structure to sizeof (RASENTRY) to identify the 
version of the structure. This parameter can be NULL. 


IpdwEntrylnfoSize 
Pointer to a variable that contains the size, in bytes, of the IpRasEntry buffer. On 
return, the function sets this variable to the number of bytes required. This parameter 
can be NULL if the joRasEntry parameter is NULL. : 


To determine the required buffer size, call RasGetEntryProperties with /oRasEntry 
set to NULL and */pdwEntryIinfoSize set to zero. The function returns the ee 
buffer size in */odwEntryInfoSize. 7 


lpbDevicelnfo 
Pointer to a buffer that receives device-specific configuration information. This is 
opaque TAPI device configuration information that you should not manipulate directly. 
This parameter can be NULL. For more information about TAPI device configuration, 
see the lineGetDevConfig function in the TAPI Programmer's Reference in the 
Platform SDK. 
Windows NT/2000: This parameter is unused. The calling function should set this 
parameter to NULL. 

IpdwDevicelnfoSize 
Pointer to a variable that contains the size, in bytes, of the buffer specified by the 
IpbDevicelnfo parameter. On return, the function sets this variable to the number of 
bytes required. This parameter can be NULL if the /pbDevicelnfo parameter s NULL. 
To determine the required buffer size, call RasGetEntryProperties with | 
IpbDeviceinfo set to NULL and */pdwDevicelnfoSize set to zero. The function returns 
the required buffer size in */odwDevicelnfoSize. 
Windows NT/2000: This parameter is unused. The calling function should set this 

- parameter to NULL. | 
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Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value can be one of the following error codes. 


Value Meaning 

ERROR_INVALID_PARAMETER The function was called with an invalid parameter. 

ERROR_INVALID_SIZE The value of the dwSize member of the 
lpRasEniry is too small. _ 

ERROR_BUFFER_INVALID The address or buffer specified by /oRasEntry is 
invalid. 

ERROR_BUFFER_TOO_SMALL The buffer size indicated in jodwEntryinfoSize is 

too small. 

ERROR_CANNOT_OPEN_ | The phone book is corrupted or is missing 

PHONEBOOK components. 

ERROR_CANNOT_FIND_ The phone book entry does not exist. 


PHONEBOOK_ENTRY 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Requires Windows 95 OSR2 or later. | 

Header: Declared in Ras.h. | 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASENTRY, RasSetEntryProperties 


RasGetErrorString 


The RasGetErrorString function obtains an error message string for a specified RAS 
error value. Pe: 
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Parameters 

uErrorValue | 
Specifies the error value of interest. These are values returned by one of the RAS 
functions: those listed in the RAS header file. 

_IpszErrorString 
Pointer to a buffer that the function will write the error string to. This parameter must 
not be NULL. 

cBufSize — 
Specifies the size, in characters, of the buffer pointed to by /pszErrorString. 


Return Values 

If the function succeeds, the return value is zero. 

If the function fails, the return value is a nonzero error value. This value is 
ERROR_INVALID PARAMETER or the GetLastError value returned from the functions 


GlobalAlloc or LoadString. The function does not set a thread's last error information; 
that is, there is no GetLastError information set by the RasGetErrorString function. 


Remarks 


There is no way to determine in advance the exact size in characters of an error 
message, and thus the size of buffer required. Error messages will generally be 80 
characters or fewer in size; a buffer size of 256 characters will always be adequate. A 
buffer of insufficient size causes the RasGetErrorString function to fail, returning 
ERROR_INSUFFICIENT_BUFFER. Note that buffer sizes are specified in characters, 
not bytes; thus, the Unicode version of RasGetErrorString requires a 512 byte buffer to 
guarantee that every error message will fit. 


Windows NT/2000: Requires Windows NT 3. 1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. ee 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
GlobalAlloc, LoadString 
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RasGetLinkStatistics 


The RasGetLinkStatistics function retrieves accumulated statistics for the specified link 
in a RAS multilink connection. | 


Parameters 


hRasConn 


Handle to the connection. Use RasDial or RasEnumConnections to obtain this 
handle. 


dwSubEntry 
Specifies the subentry that corresponds to the link for which to retrieve statistics. 


lpStatistics 


Pointer to a RAS_STATS structure to receive the statistics. Set the dwSize member 
of this structure to sizeof(RAS_STATS) before calling RasGetLinkStatistics. This 
parameter cannot be NULL. | 


Return Values 
If the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value is one of the following error codes. 


Value Meaning 


E_INVALID_ARG At least one of the following is true: the hRasConn 
parameter is zero, the dwSubEntry parameter is zero, the 
loStatistics parameter is NULL, or the value specified by 
the dwSize member of the RAS_STATS structure 


specifies a version of the structure that is not supported by 
the operating system in use. 


ERROR_NOT_ENOUGH__ The function could not allocate sufficient memory to 
MEMORY : complete the operation. 


Other Use FormatMessage to retrieve the system error 
message that corresponds to the error code returned. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 
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Ipcb 
Pointer to a variable that, on entry, specifies the size in bytes of the buffer pointed to 
by /pprojection. On exit, this variable contains the size of the buffer needed to contain 
the specified projection information. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is an error code. The function may return a nonzero 
RAS error code, or one of the following error codes. 


Value Meaning 


ERROR_BUFFER_TOO_SMALL The buffer pointed to by /pprojection is not large 
| enough to contain the requested information. 


ERROR_INVALID_HANDLE The hrasconn parameter is not a valid handle. 
ERROR_INVALID PARAMETER One of the parameters is invalid. 
ERROR_INVALID_SIZE The dwSize member of the structure pointed to by 
| Ipprojection specifies an invalid size. 7 
ERROR_PROTOCOL_NOT_ The control protocol for which information was 
CONFIGURED requested neither succeeded nor failed, because 


the connection’s phone book entry did not require 
that an attempt to negotiate the protocol be made. 
This is a RAS error code. 


Remarks 

Remote access projection is the process whereby a remote access server and a remote 
client negotiate network protocol-specific information. A remote access server uses this 
network protocol-specific information to represent a remote client on the network. 


Windows NT/2000: Remote access projection information is not available until the 
operating system has executed the RasDial RASCS_Projected state on the remote 
access connection. If RasGetProjectioninfo is called prior to the RASCS _Projected 
state, it returns ERROR_PROJECTION_NOT_COMPLETE. 


Windows 95: Windows 95 Dial-Up Networking does not support the RASCS_Projected — 
state. The projection phase may be done during the RASCS_Authenticate state. If the 
authentication is successful, the connection operation proceeds to the 

RASCS_ Authenticated state, and projection information is available for successfully 
configured protocols. If RasGetProjectioninfo is called prior to the : 

RASCS. _Authenticated state, it returns ERROR_PROTOCOL_NOT_ CONFIGURED. 
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Windows NT/2000: Requires Windows NT 3. 1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, RASAMB, 
RasDial, RasEnumConnections, RASPPPNBF, RASPPPIPX, RASPPPIP, 
RASPROJECTION 


RasGetSubEntryHandle 


The RasGetSubEntryHandle function retrieves a connection handle for a specified 
subentry of a multilink connection. 


Parameters 
hrasconn 


Specifies an HRASCONN connection handle retuimed by the RasDial function for a 
multilink phone book entry. 


dwSubEntry 
Specifies a valid subentry index for the phone book entry. 


Iphrasconn 


Pointer to an HRASCONN variable that receives a connection handle that represents 
the subentry connection. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value can be one of the following error codes. 


: Value | | _ Meaning 


ERROR_ INVALID_HANDLE _ The hrasconn connection handle does not represent a 
connected phone book entry. 


(continued) 
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(continued) 
Value | Meaning 


ERROR_PORT_NOT_OPEN _ The hrasconn and dwSubEntry parameters are valid, 
but the specified subentry is not connected. 


ERROR_NO_MORE_ITEMS _ The value specified by dwSubEntry exceeds the 
maximum number of subentries for the phone 
book entry. 


Remarks 


The connection handle specified in the hrasconn parameter refers to the entire multilink 
connection, but the connection handle returned in the */phrasconn parameter refers only 
to the subentry connection. You can use the subentry connection handle in any function 
that accepts an hrasconn parameter, including the RasHangUp, | 
RasGetConnectStatus, and RasGetProjectioninfo functions. The projection 
information returned by RasGetProjectioninfo for a multilink entry is the same for the 
each of the subentry connection handles as it is for the main connection handle. 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Unsupported. 

Header: Declared in Ras.h. | | 

Library: Use Rasapi32.lib. ee | 7 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, 
RasGetConnectStatus, RasGetProjectioninfo, RasHangUp 


RasGetSubEntryProperties 


_ The RasGetSubEntryProperties function retrieves information about a subentry for a 
specified phone book entry. | | 


is passion 
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Parameters 

lpszPhonebook 
Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a phone book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog box. 


loszEntry 
Pointer to a null-terminated string containing the name of an existing entry in the 
phone book. 


dwSubEntry 
Specifies the one-based index of the subentry.. 


lpRasSubEntry 
Pointer to a RASSUBENTRY structure followed by additional bytes for the alternate 
phone number list, if there is one. The structure receives the information about the 
specified subentry. Before calling the function, set the dwSize member of the 
structure to sizeof (RASSUBENTRY ) to identify the version of the structure. This 
parameter can be NULL. 


lpdwcb 
Pointer to a variable that contains the size, in bytes, of the JoRasSubEntry buffer. On 
return, the function sets this variable to the number of bytes returned, or the number 
of bytes required if the buffer is too small. This parameter can be NULL if 
loRasSubEntry is NULL. 


IpbDeviceConfig 
Pointer to a TAPI device configuration block. This parameter is currently inuised, The 
caller should pass NULL for this parameter. For more information about TAPI device 
configuration blocks, see the function lineGetDevConfig. 

lpcbDeviceConfig 
Pointer to a DWORD to receive the size of the TAPI device configuration block. This 
parameter is currently unused. The caller should pass NULL for this parameter. 


Return Values 
If the function succeeds, the return value | is zero. 


If the function fails, the return value can be one of the following error (codes: 
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Value | : Meaning» | 

ERROR_INVALID_PARAMETER _ The function was called with an invalid parameter. 

ERROR_BUFFER_INVALID The address or buffer specified by JpbRasSubEntry 
is invalid. 


ERROR_BUFFER_TOO_SMALL The /oRasSubEntry buffer is too small. The Jodwcb 
variable receives the required buffer size. 


ERROR_CANNOT_OPEN_ _ The phone book is corrupted or is missing 
PHONEBOOK components. 
ERROR_CANNOT_FIND_ The phone book entry does not exist. 


PHONEBOOK_ENTRY 


Remarks 


A RAS phone book entry can have zero or more subentries, each minimally consisting of 
a device and a phone number. A phone book entry with multiple subentries can be 
configured to dial the first available or all subentries when the entry is dialed. 


Use the RasGetEntryProperties function to retrieve a RASENTRY structure containing 
information about the subentries of a phone book entry. The dwSubEntries member 
indicates the number of subentries and the dwDialMode member indicates the dialing 
configuration. 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. . 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


: Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasGetEntryProperties, RASENTRY, RasSetSubEntryProperties, RASSUBENTRY | 


RasHangUp — 


The RasHangUp function terminates a remote access connection. The connection is 
specified with a RAS connection handle. The function releases all RASAPI32.DLL 
resources associated with the handle. 
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Parameters 

hrasconn 
Specifies the remote access connection to terminate. This is a handle returned from a 
previous call to RasDial or RasEnumConnections. 


Return Values 
If the function succeeds, the return value is zero. 


lf the function fails, the return value is a nonzero error value listed in ‘the RAS header file, 
or ERROR_INVALID HANDLE. 


Remarks | | 
The connection is terminated even if the RasDial call has not yet been completed. 


After this call, the hrasconn handle can no longer be used. 


An application should not call RasHangUp and then immediately exit. The connection 
‘state machine needs time to properly terminate. If the system prematurely terminates the 
state machine, the state machine may fail to properly close a port, leaving the port in an 
inconsistent state. A simple way to avoid this problem is to call Sleep(3000) after 
returning from RasHangUp; after that pause, the application can exit. A more responsive 
way to avoid the problem is, after returning from RasHangUp, to call 
RasGetConnectStatus(hrasconn) and Sleep(0) in a loop until RasGetConnectStatus 
returns ERROR_INVALID_HANDLE. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 
Library: Use Rasapi32.lib. 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASCONN, RasCustomHangUp, RasDial, RasEnumConnections, 
RasGetConnectStatus, Sleep 


RasinvokeEapUl 


The RasInvokeEapUI function displays a custom user interface to obtain Extensible 
Authentication Protocol (EAP) information from the user. 
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Parameters 
hRasConn 
Handle to the connection returned by RasDial. 


dwSubEntry 
Specifies the subentry returned in the callback. 


lpExtensions 


Pointer to a RASDIALEXTENSIONS structure. This structure should be the same as 


that passed to RasDial when restarting from a paused state. The dwSize member of 
the RASDIALEXTENSIONS structure must be set to 


sizeof(RASDIALEXTENSIONS). This parameter cannot be NULL. 


hwnd 
Handle to the parent window to use when displaying the EAP user interface. 


Return Values 
If the function succeeds, the return value is NO. ERROR. 


If the function fails, the return value is one of the following error codes. 


Value | Meaning 
ERROR_INVALID_ The hRassConn parameter is zero, or the /pExtensions 
HANDLE > parameter is NULL. 


ERROR_INVALID_SIZE The value of the dwSize member of the 
RASDIALEXTENSIONS structure specifies a version of the 
Structure that isn’t supported by the operating system in use. 


Other Use FormatMessage to retrieve the system error message 
| that corresponds to the error code returned. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 


Chapter 7 RAS Functions 173 


~ Remote Access Service (RAS) Overview, Remote Access Service Functions, RasDial, 
RASDIALEXTENSIONS, RASEAPINFO 


RasMonitorDlg 


The RasMonitorDig function displays the Dial-Up Networking Monitor property sheet 
that describes the status of RAS connections. 


Parameters 


IpszDeviceName | 
Pointer to a null-terminated string that specifies the name of the device to display — 
initially. If this parameter is NULL, or if the specified device does not exist, the _ 
property sheet displays the first device. . , 


loInfo | | | 
Pointer to a RASMONITORDLG structure that contains additional input and output 
parameters. On input, the dwSize member of this structure must specify 
sizeof(RASMONITORDLG). If an error occurs, the dwError member returns an error 
code; otherwise, it returns zero. 


Return Values 
If the user hangs up a connection, the return value is a nonzero value. © 


If an error occurs, or if the user closes the dialog box without hanging up a connection, 
the return value is zero. If an error occurs, the dwError member of the 
| RASMONITORDLG structure returns a nonzero system error code or RAS error code. | 


Remarks © Die 
The following sample code invokes the RAS monitor dialog: 


(continued) 
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(continued) ! | = 4 


ee 
 . 
es 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 

_ Header: Declared in Rasdlg.h. _ | 3 
Library: Use Rasdig.lib. 


Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASMONITORDLG | 


RasPBDligFunc 


; The RasPBDlgFunc function is an application-defined callback function that receives 
notifications of user activity while the RasPhonebookDlg dialog box is open. 


Parameters et ee ee oa 
dwCallbackld : ee Sete at os ae | | 
Specifies the application-defined value that was specified in the dwCallback member 
7 of the RASPBDLG structure passed to the RasPhonebookDlg function. 


dwEvent 
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A set of bit flags that indicates the event that occurred. This parameter is one of the 


following values. 
Value 


RASPBDEVENT_ 


AddEntry 


RASPBDEVENT_ 


EditEntry 


RASPBDEVENT_ 


RemoveEntry 


RASPBDEVENT_ 


DialEntry 


RASPBDEVENT_ 


EditGlobals 


RASPBDEVENT _ 


NoUser 


RASPBDEVENT_ 


NoUserEdit 


Meaning 


Received when the user creates a new phone book entry or 
copies an existing phone book entry. The pszText parameter is 
the name of the new or copied entry. The pData Parr is 
undefined. 


Received when the user changes an existing phone book entry. 
The pszText parameter is the name of the modified entry. The 
pDaita parameter is undefined. 


Received when the user deletes a phone book entry. The 
pszText parameter is the name of the deleted ae The pData 
parameter is undefined. | 

Received when the user successfully dials an eniy. The 
pszText parameter is the name of the newly connected entry. 
The pData parameter is undefined. i 
Received when the user makes changes in the User 
Preferences property sheet. The pszText parameter is the full 


_ path of the default phone book file selected by the user. The 


pData parameter is undefined. 


This event is also received during dialog atartup if the 
loszPhonebook parameter of the RasPhonebookDlig call is 
NULL. In this case, the event informs the caller of the path of 
the default phone book. 


Received during dialog box initialization when the 
RASPBDFLAG_NoUser flag is set. The pData parameter is a 
pointer to a RASNOUSER structure. The callback function 
should fill the structure with the user’s logon credentials and 
dialog time out. The RasPhonebookDig function then uses the 


supplied credentials for authentication by the remote server. 
_. The pszText parameter is undefined. 


~ Received if the RASPBDFLAG__ NoUser flag is set and ithe user 


changes the credentials that you supplied during the © 
RASPBDEVENT_NoUser event. The pData saramoter isa 
pointer to a RASNOUSER structure containing the updated 
credentials. This occurs during a dialing operation if the user 


~ changes his or her password, or if the authentication fails and 


the user retries authentication with different credentials. The 
pszteoxt eo is undefined. 
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pszText 


Pointer to an.additional string argument whose meaning depends on the event 
indicated in the dwEvent parameter. 


pData 


Pointer to an additional buffer argument whose meaning depends on the event 
indicated in the dwEvent parameter. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 


Header: Declared in Rasdig.h. 
Unicode: Declared as Unicode and ANSI prototypes. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASNOUSER, RasPhonebookDlg 


RasPhonebookDlg 


The RasPhonebookDig function displays the main Dial-Up Networking dialog box. 
From this modal dialog box, the user can dial, edit, or delete a selected phone book 


entry, create a new phone book entry, or specify user preferences. The 
RasPhonebookDig function returns when the dialog box closes. 


Parameters 


IpszPhonebook 


Pointer to a null-terminated string that specifies the full path and file name of a phone 
book (PBK) file. If this parameter is NULL, the function uses the current default phone 
book file. The default phone book file is the one selected by the user in the User 
Preferences property sheet of the Dial-Up Networking dialog box. 

loszEntry 


Pointer to a null-terminated string that contains the name of the phone book entry to 


highlight initially. If this parameter is NULL, or if the specified entry does not exist, the 
dialog box highlights the first entry in the alphabetic list. 
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loInfo 


Pointer to a RASPBDLG structure that contains additional input and output 
parameters. On input, the dwSize member of this structure must specify 


f(RASPBDLG). If an error occurs, the dwError member returns an error code 


otherw 


SIzeo 
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Implemented as Unicode and ANSI versions on Windows NT/2000. 


Unicode 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 


RASPBDLG 
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RasRenameEntry | 


The RasRenameEntry function changes the name of an entry in a phone book. 


Parameters 


lpszPhonebook | 
Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a Phone Book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog box. 


Windows 95: This parameter should always be NULL. Dial-up networking stores 
phone book entries in the registry rather than in a phone book file. 


IpszOldEntry 
| Pointer to a null-terminated string containing an existing entry name. 


IpszNewEntry 
Pointer to a null-terminated string containing the new entry name. Before calling 


RasRenameEntry, call the RasValidateEntryName function to validate the new 
entry name. 


Return Values 
If the function succeeds, the return value is zero. 


lf the function fails, the return value is one of the following error codes. 


Value Meaning 

ERROR_INVALID_NAME The loszNewEntry name is invalid. 
ERROR_ALREADY_EXISTS — An entry with the IpszNewEntry name already exists. 
ERROR_CANNOT_FIND_ The phone book entry does not exist. 


PHONEBOOK_ENTRY 


Remarks a | 


The RasRenameEntry function allows entry names that would not be accepted by the 
dial-up networking user interface. The entry names specified in RasRenameEntry can 
consist of any string that adheres to the following conditions. 
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1. The string cannot have a length greater than RAS_MaxEntryName (as defined in 
Ras.h). 


2. The string cannot consist entirely of space or tab characters. 
3. The first character in the string cannot be a period character (“.”). — 


The following code sample renames the phone book entry with the name specified by 
loszOldEntry to the new name specified by joszNewEntry. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 OSR2 or later. 
Header: Declared in Ras.h. 


Library: Use Rasapi32.lib. | 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 


RasValidateEntryName | 3 | | a 


~RasSetAutodialAddress =  — | 
The RasSetAutodialAddress function can add an address to the AutoDial mapping 


database. Alternatively, the function can delete or modify the data associated with an 
existing address in the database. | | 


Parameters 
lpszAddress 


Pointer to a null-terminated string that specifies the address to add, delete, or modify. 


This can be an IP address, Internet host name (“www.microsoft.com”), or NetBIOS 
name (“products1”). 
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dwReserved 
Reserved; must be zero. 


lpAutoDialEntries 
Pointer to an array of one or more RASAUTODIALENTRY structures to be 
associated with the /joszAddress address. If |JoAutoDialEntries is NULL and 
dwebAutodialEntries is zero, RasSetAutodialAddress deletes all structures 
associated with /oszAddress from the mapping database. 
dwebAutoDialEntries 
Specifies the size, in bytes, of the /oAutodialEntries buffer. 
dwcAutoDialEntries 


Specifies the number of RASAUTODIALENTRY structures in the /pAutoDialEntries 
buffer. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is one of the following error codes. 


Value Meaning 


ERROR_INVALID_ SIZE The dwSize member of the RASAUTODIALENTRY 
structure is an invalid value. 


ERROR_INVALID_PARAMETER _ The /pszAddress parameter was NULL. 


Remarks 

An address in the AutoDial mapping database can have any number of associated 
RASAUTODIALENTRY entries. Each entry specifies AutoDial information for a 
particular TAPI dialing location. 


lf the address specified by the |oszAddress parameter is an existing address in the 
database and the /pAutoDialEntries parameter is not NULL, the 
RasSetAutodialAddress function modifies the set of AutoDial entries associated with 
the address. If an entry in the /oAutoDialEntries array specifies a dialing location for 
which the address already has an entry, the function replaces the existing entry with the 
new entry. Otherwise, the function simply adds the /pAutoDialEntries entries to the set of 
entries for the address. 


If the JoszAddress address exists in the database and /pAutoDialEntries is NULL and 
dwebAutodialEntries is zero, RasSetAutodlalAddress deletes the address from the 
database. 


If the JoszAddress address does not exist in the database, RasSetAutodialAddress 
adds the address to the database. The /pAutoDialEntries parameter specifies the 
AutoDial entries to associate with the new address. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 


Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASAUTODIALENTRY, RasEnumAutodialAddresses, RasGetAutodialAddress 


-RasSetAutodialEnable © 


The RasSetAutodialEnable function enables or disables the AutoDial feature for a 
specified TAPI dialing location. For more information about TAPI dialing locations, see 
the (TAPI) Programmer's Reference in the Platform SDK documentation. 


Parameters 
dwDialingLocation | 
Specifies the identifier of a TAPI dialing location. 
fEnabled ane 


! 


Specify TRUE to enable AutoDial for the specified dialing location, or FALSE to 
disable it. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value is a nonzero error code. 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Unsupported. | | | | 
Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. | | | 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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Remote Access Service (RAS) Overview, Remote Access Service Functions, 


RasGetAutodialEnable 


RasSetAutodialParam 


The RasSetAutodialParam function sets the value of an AutoDial parameter: 


Parameters 
—dwKkey | 
Specifies the AutoDial parameter to set. This parameter can be one of the following 
values. | 
Value Meaning | 
RASADP_ The /pvValue parameter points to a DWORD 
DisableConnectionQuery value. If this value is zero (the default), AutoDial 
displays a dialog box to query the user before 
. creating a connection. If this value is 1, and the 
AutoDial database has the phone book entry to 
dial, AutoDial creates a connection without 
7 : displaying the dialog box. 
RASADP_ The JovValue parameter points to a DWORD 


LoginSessionDisable 


value. If this value is 1, the system disables all 


AutoDial connections for the current logon 


session. If this value is zero (the default), AutoDial 
connections are enabled. The AutoDial system 
service changes this value to zero when a new 
user logs on to the workstation. 


Value 


RASADP _ 
SavedAddressesLimit 


RASADP __ 
FailedConnectionTimeout 


RASADP_ | 
ConnectionQueryTimeout 


IpvValue 
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Meaning 


The /pvValue parameter points to a DWORD value 
that indicates the maximum number of addresses 


that AutoDial stores in the registry. AutoDial first 


stores addresses that it used to create an AutoDial 
connection; then it stores addresses that it learned 
after a RAS connection was created. Addresses 
written using the RasSetAutodialAddress 
function are always saved, and are not included in 
calculating the limit. The default value is 100. 


The /ovValue parameter points to a DWORD value 
that indicates a time-out value, in seconds. When 
an AutoDial connection attempt fails, the AutoDial 
system service disables subsequent attempts to 
reach the same address for the time-out period. 
This prevents AutoDial from displaying multiple 
connection dialog boxes for the same logical 
request by an application. The default value is 5. 


The /pvValue parameter points to a DWORD value 


that indicates a time-out value, in seconds. Before 


~ attempting an AutoDial connection, the system will 
display a dialog asking the user to confirm that the 


system should dial. The dialog has a countdown 
timer that will terminate the dialog with a “Do not 
dial” selection if the user takes no action. The 
DWORD value pointed to by lpvValue specifies 
the initial time on this countdown timer. — 


Pointer to a buffer that contains the new value for the specified parameter. 


dwecb Value 


Specifies the size, in bytes, of the value in the /ovValue buffer. 


Return Values 


If the function succeeds, the return value is zero. 


lf the function fails, the return value can be one of the following error codes. 


Value 


ERROR_INVALID_PARAMETER 


~ ERROR_INVALID_SIZE 


Meaning 


The dwKey or IpvValue parameter is invalid. 
The size specified by the dwcbValue is invalid. © 
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Windows NT/2000: Requires Windows NT 4.0 or later. | 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 


Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasGetAutodialParam, RasSetAutodialAddress 


RasSetCredentials 


The RasSetCredentials function sets the user credentials associated with a specified 
RAS phone book entry. 


Parameters 


lpszPhonebook 


Pointer to a null-terminated string that specifies the full path and file name of a phone 
book (PBK) file. If this parameter is NULL, the function uses the current default phone 
book file. The default phone book file is the one selected by the user in the User 
Preferences property sheet of the Dial-Up Networking dialog box. 


IposzEntry 
Pointer to a null-terminated string that contains the name of a phone book entry. 


lpCredentials 
Pointer to a RASCREDENTIALS structure that specifies the user credentials to set for 


the specified phone book entry. Before calling RasSetCredentials, set the dwSize 
member of the structure to sizeof (RASCREDENTIALS). Set the dwMask member to 
indicate the credential information to be set. 
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fClearCredentials | 
Specifies a flag that indicates whether RasSetCredentials clears existing credentials 
by setting them to the empty string, “’. If this flag is TRUE, the dwMask member of 
the RASCREDENTIALS structure indicates the credentials that the function sets to 
the empty string. If this flag is FALSE, the function sets the indicated credentials 
according to the contents of their corresponding RASCREDENTIALS members. 


~ Return Values 
_ If the function succeeds, the return value is zero. 


If the function fails, the return value is one of the following error codes. 


Value Meaning 

ERROR_CANNOT_OPEN_ The epee phone book cannot be found. 
PHONEBOOK | 

ERROR_CANNOT_FIND_ The specified entry does not exist in the eas 
PHONEBOOK_ENTRY book. 

ERROR_INVALID_PARAMETER — The IpCredentials parameter was NULL. 
ERROR_INVALID_SIZE The dwSize member of the RASCREDENTIALS 


structure is an unrecognized value. 


Remarks 7 

The RasSetCredentials function sets the user r credentials associated with a specified 
RAS phone book entry. The credentials stored with a phone book entry are the 
credentials of the last user to successfully connect using the specified phone book entry, 
or the credentials subsequently specified in a call to the RasSetCredentials or 
RasSetEntryDialParams function for the phone book entry. 


The RasSetCredentials function is the preferred way of securely storing credentials with 
a phone book entry. RasSetCredentials supersedes the RasSetEntryDialParams 
function, which may not be supported in future releases of Windows 2000. 


Windows 2000 and later versions: If the szPassword member of the 
RASCREDENTIALS structure contains the password handle returned by 
RasGetCredentials or RasGetEntryDialParams, RasSetCredentials returns 
successfully without changing any currently saved password. 


The following code sample sets the credentials for the phone book entry with the name 
“mazy’. 
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_ (continued) 
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Return Values 
lf the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value is one of the following error codes. 


Value Meaning 


E_INVALIDARG The dwSizeofCustomAuthData parameter is zero, or the 
pbCustomAuthData parameter is NULL. 


ERROR_CANNOT_OPEN_ RasSetEapUserData was unable to open the specified 


PHONEBOOK phone book file. 

ERROR_CANNOT_FIND_ RasSetEapUserData was unable to find the specified 
PHONEBOOK_ENTRY entry in the phone book. 

Other | Use FormatMessage to retrieve the system error 


message that corresponds to the error code returned. 


Windows NT/2000: Requires Windows 2000. a 
Windows 95/98: Unsupported. | 
7 Header: Declared in Ras.h. 
Library: Use Rasapi32.lib. 
Unicode: Implemented as Unicode and ANSI versions on Windows 2000. 


RasGetCustomAuthData, RasSetEapUserData 


RasSetEapUserData 


— Use the RasSetEapUserData function to store user-specific Extensible Authentication 
Protocol (EAP) information for the specified phone book entry in the registry. 
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Parameters 


hToken | 
Handle to a primary or impersonation access token that represents the user for which 
to store data. This parameter can be NULL if the function is called from a process 
already running in the user’s context. 


pszPhonebook 
Pointer to a null-terminated string containing the full path of the phone book (PBK) file. 
If this parameter is NULL, the function will use the system phone book. 


pszEntry 
Pointer to a null-terminated string containing an existing entry name. 


pbEapData 
Pointer to the data to store for the user. 


dwSizeofEapData 
Specifies the size of the data pointed to by the pbEapData parameter. 


Return Values 
If the function succeeds, the return value is ERROR_SUCCESS. 


lf the function fails, the return value is one of the following error codes. 


Value Meaning 


E_ INVALIDARG The dwSizeofEapData parameter is zero, or the 
pbEapData parameter is NULL. 


ERROR_CANNOT_ OPEN_ RasSetEapUserData was unable to open the specified 


PHONEBOOK - phone book file. 

ERROR_CANNOT_FIND_ RasSetEapUserData was unable to find the specified 
PHONEBOOK_ENTRY entry in the phone book. | 

Other | Use FormatMessage to retrieve the system error 


message that corresponds to the error code returned. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows 2000. 


_ Remote Access Service (RAS) Overview, Remote Access Service Functions, 
_ RasGetEapUserData, RasInvokeEapUI 
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RasSetEntryDialParams 


The RasSetEntryDialParams function changes the connection information saved by the 
last successful call to the RasDial or RasSetEntryDialParams function for a specified 
phone book entry. 


Parameters 
loszPhonebook © 


Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 

file name of a Phone Book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog box. | 


Windows 95: Dial-up networking stores phone book entries in the registry rather than 


in a phone book file. 
lprasdialparams 


Pointer to a RASDIALPARAMS structure containing the connection parameters to be 
associated with the phone book entry. RasSetEntryDialParams uses the structure’s 


members as follows. 


Member Description 

dwSize Must specify the sizeof(RASDIALPARAMS) to identify the 
version of the structure. 

szEntryName A null-terminated string that identifies the phone book entry 
to set parameters for. 

szPhoneNumber Not used. Set to NULL. 


szCallbackNumber 


szUserName 


A null-terminated string containing the callback phone 
number. If szCallbackNumber is an empty string (“’ ), the 
callback number is not changed. 


A null-terminated string containing the logon name of the 
user associated with this entry. If szUserName is an empty 
String, the user name is not changed. 


(continued. 
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(continued) 
Member 


szPassword 


szDomain 


dwSubEntry 


dwCallbacklid 


fRemovePassword 


Description 


A null-terminated string containing the password for the user 
specified by szUserName. If szUserName is an empty 
string, the password is not changed. If szPassword is an 
empty string and fRemovePassword is FALSE, the password 
is set to the empty string. If fRemovePassword is TRUE, the 
password stored in this phone book entry for the user 
specified by szUserName is removed regardless of the 
contents of the szPassword string. 


Windows NT 4.0 and later: The password is changed to the 
string specified by szPassword regardless of whether 
szUserName is an empty string. 


Windows 2000 and later: If szPassword contains the 
password handle returned by RasGetCredentials or 
RasGetEntryDialParams, RasSetEntryDialParams returns 
successfully without changing any currently saved password. 


A null-terminated string containing the name of the domain to 
log on to. If szDomain is an empty string, the domain name 
is not changed. 

Specifies the (one-based) index of the initial subentry to dial 
when establishing the connection. | 


Not used; should be zero. 


Specifies whether to remove the sine book entry’s stored password for the user 
specified by /porasdialparams->szUserName. If fRemovePassword is TRUE, the 
password is removed. Setting fRemovePassword to TRUE is equivalent to checking 
the “Unsave Password” checkbox in Dial-Up Networking. When setting the password 
or other properties of a phone book entry, set fRemovePassword to FALSE. 


Return Values 


If the function succeeds, the return value Is zero. 


Value 


_ If the function fails, the return value can be one of the following error codes. | 


Description 


ERROR_BUFFER_INVALID — The address or buffer specified by /prasdialparams is 


ERROR_CANNOT_OPEN_ 


PHONEBOOK 


ERROR_CANNOT_FIND_ 


PHONEBOOK_ENTRY 


invalid. 
The phone book is corrupted or missing components. 


The phone book entry does not exist. 
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Remarks | 
To create a new phone book entry, use the RasSetEntryProperties function. 


Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 


Library: Use Rasapi32.lib. 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, 
_ RasGetEntryDialParams, RasSetEntryProperties 


-RasSetEntryProperties 


The RasSetEntryProperties function changes the connection information for an entry in 
the phone book or creates a new phone book entry. 


Parameters 
loszPhonebook 


Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a Phone Book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 


user in the User Preferences property sheet of the Dial-Up Networking dialog box. 
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loszEntry © 
Pointer to a null-terminated string containing an entry name. 


If the entry name matches an existing entry, RasSetEntryProperties modifies the 
properties of that entry. 


If the entry name does not match an existing entry, RasSetEntryProperties creates a 
new phone book entry. For new entries, call the RasValidateEntryName function to 
validate the entry name before calling RasSetEntryProperties. 


lpRasEntry 
Pointer to a RASENTRY structure that contains the new connection data to be 
associated with the phone book entry specified by the /oszEntry parameter. 
The structure might be followed by an array of null-terminated alternate phone 
number strings. The last string is terminated by two consecutive null characters. The 
dwAlternateOffset member of the RASENTRY structure contains the offset to the 
first string. 

dwEntrylnfoSize 
Specifies the size, in bytes, of the buffer specified by the JoRasEntry parameter. 


_ IpbDevicelnfo 


Pointer to a buffer containing device-specific configuration information. This is opaque 
TAPI device configuration information. For more information about TAPI device 
configuration, see the lineGetDevConfig function in the TAP! Programmer’s 
Reference in the Platform SDK. 


Windows NT/2000: This parameter is unused. The calling function should set this 
parameter to NULL. 


dwDevicelnfoSize 
Specifies the size, in bytes, of the jobDevicelnfo buffer. 


Windows NT/2000: This parameter is unused. The calling function should set this 
parameter to zero. 


Return Values 
If the function succeeds, the return value is zero. 


If the function fails, the return value can be one of the following error codes. 


Value Meaning 


ERROR_BUFFER_INVALID The address or buffer specified by JoRasEntry is invalid. 


ERROR_CANNOT_OPEN_ __ The phone book is corrupted or missing components. 
PHONEBOOK 
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Remarks 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Requires Windows 95 OSR2 or later. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RASENTRY, RasCreatePhonebookEntry, RasGetEnitryProperties, 
RasValidateEntryName 


RasSetSubEntryProperties 


The RasSetSubEntryProperties function creates a new subentry or modifies an 
existing subentry of a specified phone book entry. 


Parameters 


loszPhonebook — ee 7 


Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 
file name of a Phone Book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 
user in the User Preferences property sheet of the Dial-Up Networking dialog box. 
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loszEntry | 
Pointer to a null-terminated string containing the name of an existing entry in the 
phone book. 


dwSubEntry 
Specifies the one- -based index of the subentry. If the index matches an existing 
subentry index, the function changes the properties of that subentry. If the index does 
not match an existing index, the function creates a new subentry. | 

loRasSubEntry 
Pointer to a RASSUBENTRY structure that contains the data for the subentry. 
The structure might be followed by an array of null-terminated alternate phone 
number strings. The last string is terminated by two consecutive null characters. The 
dwAlternateOffset member of the RASSUBENTRY structure contains the offset to 
the first string. 

dwcbRasSubEntry 
Specifies the size, in bytes, of the IpRasSubEntry buffer. 

lpbDeviceConfig 
Pointer to a TAPI device configuration block. This parameter is currently unused. The 
caller should pass NULL for this parameter. For more information about TAPI device © 
configuration blocks, see the function lineGetDevConfig. 

dwcbDeviceConfig 
Specifies the size of the TAP! device configuration block. This a raineiet is currently 
unused. The caller should pass zero for this parameter. 


Return Values 
If the function succeeds, the return value is zero. 


‘If the function fails, the return value can be one of the following error codes. 


Value Meaning |  % 

ERROR_BUFFER_INVALID The address or buffer specified by lpRasEntry is 
invalid. | 

ERROR_CANNOT_FIND_ The phone book entry does not exist. 

PHONEBOOK_ENTRY | 

ERROR _CANNOT_OPEN_ The phone book is corrupted or missing 

PHONEBOOK components. 


ERROR_INVALID_ PARAMETER The function was called with an invalid SeRaineice | 


Remarks 
_ARAS phone book entry can have zero or more subentries, each minimally consisting of. 


a device and a phone number. A phone book entry with multiple subentries can be 
configured to dial either the first available ey or all subentries when the entry is 
dialed. 
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Use the RasGetEntryProperties function to retrieve a RASENTRY structure containing 
information about the subentries of a phone book entry. The dwSubEntries member 
indicates the number of subentries and the dwDialMode member indicates the dialing 
configuration. | | 


Windows NT/2000: Requires Windows NT 4.0 or later. 

Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Library: Use Rasapi32.lib. | 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


Remote Access Service (RAS) Overview, Remote Access Service Functions, 
RasGetEntryProperties, RASENTRY, RASSUBENTRY 


~ RasValidateEntryName 


The RasValidateEntryName function validates the format of a connection entry name. 
The name must contain at least one non-white-space alphanumeric character. 


Parameters 


lpszPhonebook aye | es: 

Windows NT/2000: Pointer to a null-terminated string that specifies the full path and 

file name of a Phone Book (PBK) file. If this parameter is NULL, the function uses the 
current default phone book file. The default phone book file is the one selected by the 

_user in the User Preferences property sheet of the Dial-Up Networking dialog box. 

_ IpszEntry | . | 
Se at - Pointer to a null-terminated string containing an entry name. 

Windows NT/2000: The entry name cannot begin with a period (“.”). 


ReturnValues 
If the function succeeds, the return value is ERROR_SUCCESS. _ 


If the function fails, the return value is ERROR_INVALID. NAME or 
ERROR_ALREADY_EXISTS. | 
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The following sample code validates the phone book entry specified by the variable 


Remarks 
loszEntry. 
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RasCustomScriptExecute 


RAS calls the RasCustomScriptExecute function when establishing a connection for a 
phone book entry that has the RASEO_CustomScript option set. 


Parameters 
hPort 


Handle to the port on which the connection is established. Use this handle when 
sending or receiving data on the port. 


lpszPhonebook Fie ae 
Pointer to a Unicode string containing the path to the phone book in which the entry 
for the connection resides. | 


loszEntryName 
Pointer to a Unicode string containing the name of the entry that was dialed to 
establish the connection. 


pinRasGetBuffer 
Pointer to a function of type PFNRASGETBUFFER. The custom-scripting DLL should 
use this function to allocate memory to send data to the server. 


ptnRasFreeBuffer 
Pointer to a function of type PFNRASFREEBUFFER. The custom-scripting DLL 
should use this function to free memory allocated by the pfnRasGetBuffer function. 


ptnRasSendBuftfer | 
Pointer to a function of type PFNRASSENDBUFFER. The custom-scripting DLL uses 
this function to communicate with the server over the specified port. 


ptnRasReceiveBuffer 
Pointer to a function of type PFNRASRECEIVEBUFFER. The custom-scripting DLL 
uses this function to communicate with the server over the specified port. 


pfnRasRetrieveBuffer | 
Pointer to a function of type PFNRASRETRIEVEBUFFER. The custom-scripting DLL 
uses this function to communicate with the server over the specified port. 
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hWnd 
Handle to a window that the custom-scripting DLL can use to present a user interface 
to the user. 


pRasDialParams 
Pointer to a Unicode RASDIALPARAMS structure. This structure contains the 
authentication credentials for the user. The custom-scripting DLL can modify the 
szUserName, szPassword, and szDomain members of this structure. The Point-to- 
Point Protocol (PPP) will use whatever is stored in these members when 
RasCustomScriptExecute returns. 


pvReserved | 
This parameter is reserved for future use. 


Return Values 
If the function succeeds, the return value should be ERROR_SUCCESS. 


If the function fails, the return value should be an appropriate error code from Winerror.h 
or Raserror.h. 


Remarks 
When RAS calls RasCustomScriptExecute, the pRasDialParams parameter will point 


to a Unicode RASDIALPARAMS structure. That is, the structure contains only Unicode 
strings. 


In some cases, the szUserName of the RASDIALPARAMS structure will be an empty 
string. In these case, the custom-scripting DLL should use the Unicode version of the 
GetUserName function to obtain the name of the current user. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Rasdlg.h. 

Unicode: Declared only as Unicode. 
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RasGetBuffer 


The custom-scripting DLL calls RasGetBuffer to allocate memory for Senne or 
receiving data over the port connected to the server. 
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Parameters 


ppBuffer 
Pointer to a pointer that receives the address of the returned buffer. 


pdwSize 
Pointer to a DWORD variable that, on input, contains the requested size of the buffer. 


On output, this variable contains the actual size of the buffer allocated. 


Return values 
If the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value can be one of the following error codes. 


Value Meanin 
ERROR_OUT_OF_BU FFERS RAS cannot allocate anymore buffer space. 
Remarks 


The maximum buffer size that can be obtained from is 1500 bytes. 


The custom-scripting DLL calls RasGetBuffer through a function pointer. The function | 
; _ pointer is passed to the custom-scripting DLL as a parameter when RAS calls the DLL’s 


implementation of RasCustomScriptExecute. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. — 
Header: Declared in Rasdlg.h. 
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_ RasFreeBuffer a oe ae 


The custom-scripting DLL calls RasFreeBuffer to release a memory buffer that was 
allocated by a previous call to RasGetBuffer. _ a 
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Parameters 


pBuffer 
Pointer to the memory buffer to free. This memory must have been obtained by a 


previous call to RasGetBuffer. 


Return values 
If the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value can be one of the following error codes. 


Value Meaning 

ERROR_BUFFER_INVALID The pointer to the buffer passed in the 
pBuffer parameter is invalid. 

ERROR_INVALID_PORT_HANDLE The handle specified by the hPort parameter 
is invalid. 

Remarks 


The custom-scripting DLL calls RasFreeBuffer through a function pointer. The function 
pointer is passed to the custom-scripting DLL as a parameter when RAS calls the DLL’s 


implementation of RasCustomScriptExecute. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Rasdlg.h. 


RAS Custom-Scripting, RasCustomScriptExecute, RasGetBuffer 


RasSendBuffer 


The custom-scripting DLL calls the RasSendBuffer function to send data to the server 
over the specified port. 
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Parameters 


hPort | 

Handle to the port on which to send the data in the buffer. This handle should be the 

handle passed in by RAS as the first parameter of the RasCustomScriptExecute 
function. 


pBuffer 
Pointer to a buffer of data to send over the port specified by the hPort parameter. 
Obtain this buffer using RasGetBuffer function. 


dwSize | | 
Specifies the size of the data in the buffer pointed to by the pBuffer parameter. 


Return values 
If the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value can be one of the following error codes. 
Value Meaning 


ERROR_BUFFER_INVALID The pointer to the buffer passed in the pBuffer 
parameter is invalid. : 


ERROR_INVALID_PORT_HANDLE _ The handle specified by the hPort parameter is 
invalid. 


Remarks 


The custom-scripting DLL calls RasSendBuffer through a function pointer. The function 
pointer is passed to the custom-scripting DLL as a parameter when RAS calls the DLL’s 
implementation of RasCustomScriptExecute. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. — 
Header: Declared in Rasdlg.h. 


RAS Custom-Scripting, RasCustomScriptExecute, RasReceiveBuffer, 
RasRetrieveBuffer 


RasReceiveBuffer 


The custom-scripting DLL calls the RasReceiveBuffer function to inform RAS that it is 
ready to receive data from the server over the specified port. 
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Parameters 


hPort 
Handle to the port on which to receive the data. This handle should be the handle 
passed in by RAS as the first parameter of the RasCustomScriptExecute function. 


 pBuffer | | 
Pointer to a buffer to receive the data from the port specified by the hPort parameter. 


Obtain this buffer using RasGetBuffer function. 


pdwSize | 
Pointer to a DWORD variable that receives the size of the data returned in the buffer 


pointed to by the pBuffer parameter. 


dwTimeout , 
Specifies a time-out period in milliseconds after which the custom-scripting DLL will 


no longer wait for the data. 


hEvent 
| ~ Handle to an event object that RAS will signal when the received data is available. 


Return values 
If the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value can be one of the following error codes. 


Value | Meaning 


ERROR_BUFFER_INVALID The pointer to the buffer passed in the pBuffer 
: | parameter is invalid. 


ERROR_INVALID_PORT_HANDLE The handle specified by the hPort parameter is 
invalid. 


Remarks 


RasReceiveBuffer is an asynchronous function. RasReceiveBuffer returns 
immediately even if the data is not yet available. The custom-scripting DLL must wait on 
the event object specified by the hEvent parameter. When the data is available, RAS 
signals this event. The custom-scripting DLL should then call the RasRetrieveBuffer 
function to obtain the data. The custom-scripting DLL may pass the same buffer pointer 
in RasRetrieveBuffer that it passed in RasReceiveData. 
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RAS also signals the event object if, for some reason, the port is disconnected before 
the data is posted. In this case, RasRetrieveBuffer returns an error defined in 
Raserror.h, that indicates the cause of the failure. 


The custom-scripting DLL calls RasReceiveBuffer through a function weinte: The 
function pointer is passed to the custom-scripting DLL as a parameter when RAS calls 
the DLL’s implementation of RasCustomScriptExecute. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Rasdlg.h. 


RAS Custom-Scripting, RasCustomScriptExecute, RasSendBuffer 


RasRetrieveBuffer 


The custom-scripting DLL calls the RasRetrieveBuffer function to obtain data received — 
from the RAS server over the specified port. The custom-scripting DLL should call 

-RasRetrieveBuffer only after RAS has signaled the event ppieet passed in the call to. 
RasReceiveBuffer. 


Parameters 
hPort 
Handle to the port on which to receive the data. This handle should be the handle 
passed in by RAS as the first parameter of the RasCustomScriptExecute function. 
pBuffer | 
Pointer to a buffer to receive the data from the port specified by the hPort parameter. 
Obtain this buffer using RasGetBuffer function. The value of this parameter may be 
the same as the pointer to the butter passed into the RasReceiveBuffer function. 
pdwSize | 
Pointer to a DWORD variable that receives the size of the data returned in the buffer 
alls to by the pBuffer parameter. | | 


Return Values 
If the function succeeds, the return value is ERROR_ SUCCESS. 
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If the function fails, the return value can be one of the following error codes. 


Value _ _ Meaning | 
ERROR_BUFFER_INVALID The pointer to the buffer passed in the pBuffer 


parameter is invalid. 


ERROR_INVALID_PORT_HANDLE _ The handle specified by the hPort parameter is 
7 invalid. | | 


RAS signals the event object if the port gets disconnected for some reason before the 
data is posted. In this case, RasRetrieveBuffer returns an error defined in Raserror.h, - 
that indicates the cause of the failure. | 


Remarks 


The RasRetrieveBuffer function is synchronous. When it returns, the buffer pointed to 
by the pBuffer parameter contains the data received over the specified port. The custom- 
scripting DLL should call RasRetrieveBuffer only after RAS has signaled the event 
object that the DLL passed in the call to RasReceiveBuffer. 


The custom-scripting DLL calls RasRetrieveBuffer through a function pointer. The 
function pointer is passed to the custom-scripting DLL as a parameter when RAS calls 
the DLL’s implementation of RasCustomScriptExecute. 


RAS Custom-Scripting, RasCustomScriptExecute, RasReceiveBuffer, 
RasSendBuffer 


CHAPTER 8 


RAS Structures 


Members 
dwSize 
Specifies the size, in bytes, of the RASADPARAMS structure. The system sets 
dwSize to sizeof (RASADPARAWS) to identify the version of the structure. 


hwndOwner ° : | 
Specifies the parent window for the AutoDial user interface. This member can 


be NULL. 


Use the following structures to implement RAS functionality: 


RASADPARAMS RASENTRYDLG 
RASAMB RASENTRYNAME 
RASAUTODIALENTRY RASIPADDR 
RASCONN RASMONITORDLG 
RASCONNSTATUS RASNOUSER 
RASCREDENTIALS RASPBDLG 
RASCTRYINFO RASPPPCCP 
RASDEVINFO RASPPPIP 
RASDIALDLG RASPPPIPX 
RASDIALEXTENSIONS RASPPPLCP 
RASDIALPARAMS RASPPPNBF 
RASEAPINFO RASSLIP 
RASEAPUSERIDENTITY RASSUBENTRY 
RASENTRY 

RASADPARAMS 


The RASADPARAMS structure describes the parameters that AutoDial passes to a 
RASADFunc AutoDial handler. 
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dwFlags 
Specifies a flag that indicates how to position the window of your AutoDial user 
interface. The following flag is defined. 


Flag Description 


RASADFLG_PositionDlg If this flag is set, position your window according to the 
coordinates specified by the xDIg and yDIg members. 


If this flag is not set, center your window on the window 
specified by the hwndOwner member. If hwndOwner 
is NULL, center your window on the screen. 


xDlig 
Specifies the horizontal screen coordinate of your window’s upper-left corner. Ignore 
this member if the RASADFLG_PositionDlg bit is not set in the dwFlags member. 
yDig | 
Specifies the vertical screen coordinate of your window’s upper-left corner. Ignore this 
member if the RASADFLG_PositionDlg bit is not set in the dwFlags member. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RASADFunc 


RASAMB 


The RASAMB structure contains the result of a Remote Access Server (RAS) 
Authentication Message Block (AMB) projection operation. 


The RasGetProjectionInfo function returns a RASAMB data structure when its 
rasprojection parameter has the value RASP_Amb. 
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Members 

dwSize 
Specifies the size of the structure, in bytes. Before calling the RasGetProjectioninfo 
function, set this member to sizeof(RASAMB). The function can then determine the 
version of the RASAMB data structure that the caller of RasGetProjectioninfo is 
expecting. This allows backward compatibility for compiled applications if there are 
future enhancements to the data structure. 


dwError 
Contains the result of the PPP control protocol negotiation. A value of zero indicates 
success. A nonzero value indicates failure, and is the actual fatal error that occurred 
during the control protocol negotiation, the error that Pevene? the projection from - 
completing successfully. 


szNetBiosError 
If dwError has the value ERROR_NAME_EXISTS_ON_NET, the szNetBiosError 
field contains a zero-terminated string that is the NetBIOS name that caused the 
conflict. For other values of dwError, this field contains the null string. 

bLana ; 

Specifies the NetBIOS network adapter identifier, or LANA, on which the remote 

access connection was established. This member contains the value OxFF if a 
connection was not established. 


Remarks 


The AMB protocol is used with servers that were released before PPP was adopted as 
the primary framing protocol; for example, Windows NT 3.1 and OS/2 1.3 RAS servers. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 

Unicode: Declared as Unicode and ANS! Structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasGetProjectionInfo, RASPROJECTION 


RASAUTODIALENTRY 


The RASAUTODIALENTRY structure describes an AutoDial entry associated with a 
network address in the AutoDial mapping database. An AutoDial entry specifies a 
| phone-book entry that AutoDial dials in a particular TAPI dialing location. 
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The RasGetAutodialAddress and RasSetAutodialAddress functions use this structure 
to set and retrieve information about an AutoDial entry. 


Members 


dwSize 


Specifies the size, in bytes, of the RASAUTODIALENTRY structure. Before calling 
RasGetAutodialAddress or RasSetAutodialAddress, set dwSize to 
sizeof (RASAUTODIALENTRY ) to identify the version of the structure. 


dwFlags 
Reserved; must be zero. 


dwDialingLocation 


Specifies a TAPI dialing location. For more information about TAPI dialing locations, 
see the TAPI Programmer’s Reference in the Platform SDK. 


szEntry 
Specifies a null-terminated string that names an existing phone-book entry. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasGetAutodialAddress, RasSetAutodialAddress 


RASCONN 


The RASCONN structure provides information about a remote access connection. The 
RasEnumConnections function returns an array of RASCONN structures. 


seo 
< 


Specifies the size, in bytes, of the RASCONN structure. 


hrasconn 7 
Specifies the remote access connection. This handle is used in other remote access _ 
API calls. 7 | | 


szEntryName | 
A string that specifies the phone-book entry used to establish the remote access | 

~ connection. If the connection was established using an empty entry name, this string 
consists of a PERIOD followed by the connection phone number. 


szDeviceType 
Windows NT 4.0 and later: A null-terminated string that contains the device type 
through which the connection is made. 


szDeviceName 7 | 
Windows NT 4.0 and later: A null-terminated string that contains the device name 
through which the connection is made. 


szPhonebook [ MAX_PATH ] | ye oe! 
Windows NT 4.0 and later: The full path and file name to the phone book containing 
the entry for this connection. 


dwSubEntry 
Windows NT 4.0 and later: For multilink connections, specifies the subentry index of 
one of the connected links. Subentry indices are one based. 

guidEntry | | 
Windows 2000: A GUID (Globally Unique |Dentifier) that represents the phone-book 


entry. The value of this member corresponds to that of the guidid member in the 
RASENTRY structure. | : | 
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Windows NT/2000: Requires Windows NT 3.1 or later. 

Windows 95/98: Requires Windows 95 or later. 

Header: Declared in Ras.h. 

Unicode: Declared as Unicode and ANSI structures. | : 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasEnumConnections, RasGetConnectStatus 


RASCONNSTATUS 


A RASCONNSTATUS structure describes the current status of a remote access 
connection. It is returned by the RasGetConnectStatus function. 


Members 


dwSize 
Specifies the structure size, in bytes. 


rasconnstate 
Specifies a RASCONNSTATE enumerator value that indicates the current state of the 
RasDial connection process; that is, the piece of the RasDial process that is currently 


executing. 

Two state values are especially significant. 

State Meaning 

RASCS_Connected Indicates that the connection has been successfully 


established. | 
RASCS_Disconnected _Indicates that the connection has failed. 


dwError | | 
lf nonzero, indicates the reason for failure. The value is one of the error values from 
the RAS header file or one of ERROR_NOT_ENOUGH_MEMORY or 
ERROR_INVALID_HANDLE. 
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szDeviceType 


A string that specifies the type of the current device, if available. For example, 


common device types supported by RAS are “modem”, “pad”, “switch”, “isdn”, or 
‘null’. 


szDeviceName 


A string that specifies the name of the current device, if available. This would be the 
name of the modem—for example, “Hayes Smartmodem 2400”; the name of the PAD, 


for example “US Sprint”; or the name of a switch device, for example “Racal- 
Guardata”. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 


Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasGetConnectStatus, RasDial, RASCONNSTATE 


RASCREDENTIALS = sits 


The RASCREDENTIALS structure is used with the RasGetCredentials and 


RasSetCredentials functions to specify the user credentials associated with a RAS» 
phone-book entry. 


Members | 

dwSize . pee oa 
Specifies the size, in bytes, of the RASCREDENTIALS structure. 

dwMask | a : . : 
Specifies a set of bit flags that specify the members of this structure that are valid. On 
input, set the flags to indicate the members in which you are interested. On output, 
the function sets the flags to indicate the members that contain valid data. This 
member can be a combination of the following values. 
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Value Meaning 

RASCM_UserName The szUserName member is valid. 
RASCM_Password | The szPassword member is valid. 
RASCM_Domain — The szDomain member is valid. 


Windows 2000 and later versions: When retrieving credentials using the 
RasGetCredentials function, the dwMask member contains the RASCM_Password 
flag if the system has saved a password for the specified entry. If the system has no 
password saved for this entry, dwMask does not contain RASCM_ Password. 


szUserName 
Specifies a null-terminated string that contains a user name. 


szPassword 
Specifies a null-terminated string that contains a password. 


Windows 2000 and later versions: When retrieving credentials using the 
RasGetCredentials function, the szPassword member does not receive the actual 
password. Instead, szPassword receives a handle to the saved password. You can 
substitute this handle for the saved password in calls to RasSetCredentials and 
RasDial. When presented with this handle, RasDial will retrieve and use the saved 
password. The value of this handle may change in future versions of the operating 
system; do not gEvelop code that depends on the contents or format of this value. 


szDomain 
A null-terminated string that contains a domain name. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, | 
RasGetCredentials, RasSetCredentials 


-RASCTRYINFO 


The RASCTRYINFO structure describes the direct dialing procedures for calls placed 
within a specified country. The RasGetCountrylInfo function uses this structure to 
retrieve country-specific clang information from the Windows Telephony list of country 
information. 
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For more information about country-specific dialing information, see the 
TAPI Programmer's Reference in the Platform SDK. 


Members 


dwSize | 
Specifies the size, in bytes, of the RASCTRYINFO structure. Before calling 
RasGetCountryInfo, set dwSize to sizeof (RASCTRYINFO) to identify the version of the 
structure. 


dwCountrylD 
Specifies a TAPI country identifier. Before calling RasGetCountryinfo, set 
dwCountrylD to identify the country of interest. For more information about TAPI 
country identifiers, see the TAPI Programmer’s Reference in the Platform SDK. 


If this member is 1, RasGetCountrylnfo returns information about the first country in 
the Windows Telephony list of country information. 


dwNextCountryID ae 4 = 
Specifies the TAPI country identifier of the next country to enumerate in the Windows 
Telephony list. This member is zero for the last country in the list. 


dwCountryCode 
Specifies the country code for the country identified by the dwCountryID member. 


dwCountryNameOffset 
Specifies the offset, in bytes, from the start of the structure to the start of a null- 
terminated string describing the country. The description string is either ANSI or 
Unicode, depending on whether you use the ANSI or Unicode version of 
RasGetCountryinfo. 


Remarks 


For more information on dialing procedures and telephony configuration, see the 
TAPI Programmer’s Reference in the Platform SDK. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 OSR2 or later. 
Header: Declared in Ras.h. 

Unicode: Declared as Unicode and ANSI structures. 
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Remote Access Service (RAS) Overview, Remote Access Service Structures, 
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RASDEVINFO 


The RASDEVINFO structure contains information that describes a TAPI device capable 
of establishing a RAS connection. The RasEnumDevices function uses this structure to 
retrieve information about RAS-capable devices. 


Members 


dwSize | 
Specifies the size, in bytes, of the RASDEVINFO structure. Before calling 
RasEnumDevices, set dwSize to sizeof (RASDEVINFO) to identify the version of the 
structure. 


szDeviceType 
Specifies a null-terminated string indicating the RAS device type referenced by 
szDeviceName. This member can be one of the following string constants. 


String Description 


RASDT_Modem A modem accessed through a COM port. 
RASDT_lIsdn _ An ISDN card with the corresponding NDISWAN driver installed. 


RASDT_X25 An X.25 card with the corresponding NDISWAN driver installed. 
RASDT_Vpn A virtual private network connection. 
RASDT_Pad A Packet Assembler/Disassembler. 


Windows 95: The RASDT_Vpn device type is supported on Windows 95 only if 
Microsoft Dial-Up Networking Version 1.2 is installed. The RASDT_X25 and 
RASDT_Pad device types are not supported on Windows 95. 


Windows 98: The RASDT_Vpn device type is supported on Windows 98. However, 
the RASDT_X25 and RASDT_Pad device types are not currently supported on 
Windows 98 od 


szDeviceName 
Specifies a null-terminated string containing the name of a TAPI device. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 OSR2 or later. 
Header: Declared in Ras.h. 

Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasEnumDevices | 


RASDIALDLG 


The RASDIALDLG structure is used in the RasDialDlg function to specify additional 
input and output parameters. — | 


Members 

dwSize_ -_ : : : | 
Specifies the size of this structure, in bytes. Before calling RasDialDlg, set this 
member to sizeof(RASDIALDLG) to indicate the version of the structure. If dwSize is 


not a valid size, RasDialDlg fails and sets the dwError member to 
ERROR_INVALID_SIZE. | | } | 


hwndOwner ~~ caer : | 
| Specifies the window that owns the modal RasDialDlg dialog boxes. This member 
can be any valid window handle, or it can be NULL if the dialog box has no owner. 
dwFlags 


A bit flag that indicates the options that are enabled for the dialog box. You can 
specify the following value. 
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Value Meaning 
RASDDFLAG_ lf this flag is set, RasDialDlg uses the values specified by 
PositionDlg the xDIg and yDIg members to position the dialog box. 


If this flag is not set, the dialog box is centered on the 
owner window, unless hwndOwner is NULL, in which 
case, the dialog box is centered on the screen. 


xDlig 
Specifies the horizontal screen coordinate of the upper-left corner of the dialog box. 
This value is used only if the RASDDFLAG_PositionDlg flag is set. 

yDig 
Specifies the vertical screen coordinate of the upper-left corner of the dialog box. This 
value is used only if the RASDDFLAG_PositionDlg flag is set. 


dwSubEntry 
Specifies the subentry or subentries to dial. If dwSubEntry i is zero, RasDialDlg dials 
all subentries associated with the specified phone-book entry. Otherwise, to indicate 
the index of the individual subentry to dial, dwSubEntry must be a number from one 
to the number of subentries. 


dwError 
The RasDialDlg function sets this member toa system error code or RAS error code 
if an error occurs. If no error occurs, the function sets dwError to zero. This value is 
ignored on input. 


reserved 
Reserved; must be zero. 


reserved2 
Reserved; must be zero. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Rasdlg.h. 


Remote Access Service Ne) Overview, Remote Access Service Structures, 
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RASDIALEXTENSIONS 


The RASDIALEXTENSIONS structure contains information about extended features of 
the RasDial function. You can enable one or more of these extensions by passing a 
pointer to a RASDIALEXTENSIONS structure when you call RasDial. If you do not pass 
a pointer to a RASDIALEXTENSIONS structure to RasDial, RasDial uses the default 
settings that are noted in the following descriptions. 


Members 


dwSize 
Specifies the size of this structure, in bytes. Set this member to 
sizeof(RASDIALEXTENSIONS). This indicates the version of the structure. 


| dwfOptions 


A set of bit flags that specify RasDial extensions. The following bit flags are datined: 
you must set all undefined bits to zero. 


Value Description 
RDEOPT_ If this bit flag is one, RasDial uses the prefix and suffix that is in the 
UsePrefixSuffix RAS phone book. 
| If this bit flag is zero, RasDial ignores the prefix and suffix that is in 
the RAS phone book. 
If no phone-book entry name is specified in the call to RasDial, the 
actual value of this bit flag is ignored, and it is assumed to be zero. 
RDEOPT_ If this bit flag is one, RasDial accepts paused states. Examples of 
PausedStates _ paused states are terminal mode, retry logon, change password, 


set callback number, and EAP authentication. 


If this bit flag is zero, RasDial reports a fatal error if it enters a 
paused state. 
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(continued) 
Value > 


RDEOPT_ 
lgnoreModemSpeaker 


RDEOPT_ 
SetModemSpeaker 


RDEOPT_ 
IgnoreSoftwareCompression 


RDEOPT_ | 
SetSoftwareCompression 


Description 


If this bit flag is one, RasDial ignores the modem speaker setting 
that is in the RAS phone book, and uses the setting specified by 
the RDEOPT_SetModemSpeaker bit flag. 


If this bit flag is zero, RasDial uses the modem speaker setting that 
is in the RAS phone book, and ignores the setting specified by the 
RDEOPT_SetModemSpeaker bit flag. 


If no phone-book entry name is specified in the call to RasDial, the 
choice is between using a default setting or the setting specified by 
the RDEOPT_SetModemSpeaker bit flag. The default setting is 
used if RDEOPT_IgnoreModemSpeaker is zero. The setting 
specified by RDEOPT_SetModemSpeaker is used if 
RDEOPT_IgnoreModemSpeaker is one. 


If this bit flag is one, and RDEOPT Sen ereMecemopeaner is one, 
RasDial sets the modem speaker on. 
lf this bit flag is zero, and RDEOPT _lgnoremogemSpeaKet'! is one, 
RasDial sets the modem speaker off. 


If RDEOPT _IgnoreModemSpeaker is zero, RasDial ignores ane 
value of RDEOPT_SetModemSpeaker, and sets the modem 


_ speaker based on the RAS phone-book setting or the default 


setting. 


If this bit flag is one, RasDial ignores the software compression 
setting that is in the RAS phone book, and uses the setting 
specified by the RDEOPT_SetSoftwareCompression bit flag. 


If this bit flag is zero, RasDial uses the software compression 
setting that is in the RAS phone book, and ignores the setting 


‘specified by the RDEOPT_SetSoftwareCompression bit flag. 


If no phone-book entry name is specified in the call to RasDial, the 
choice is between using a default setting or the setting specified by 
the RDEOPT_SetSoftwareCompression bit flag. The default setting 
is used if RDEOPT_IgnoreSoftwareCompression is zero. The 
setting specified by RDEOPT_SetSoftwareCompression is used if 


RDEOPT_IgnoreSoftwareCompression is one. 


If this bit flag is one, and RDEOPT_IgnoreSoftwareCompression is 
one, RasDial uses software compression. 


If this bit flag is zero, and RDEOPT_IgnoreSoftwareCompression is 
one, RasDial does not use software compression. 


lf RDEOPT_IgnoreSoftwareCompression is zero, RasDial ignores 
the value of RDEOPT_SetSoftwareCompression, and sets the 
software compression state based on the RAS phone-book setting 
or the default setting. 
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Value Description 
RDEOPT_ Used internally by the RasDialDlg function so that a Windows-95- 
PauseOnScript style logon script is executed in a terminal window visible to the 


user. Applications should not set this flag. 


The default value for each of these bit flags is zero. 


hwndParent | 
Handle to a parent window that a security DLL can use for dialog box creation and 


centering. 
Note that this is not the window that receives RasDial progress notifications. 


This member is optional; it is not required when no security DLL is defined. 
The default value for this member is NULL. 


reserved 
This member is reserved for future use. It must be set to zero. | 


reserved! 
Windows 2000: This member is reserved for future use. It must be set to zero. 


RasEaplnfo 
‘Windows 2000: A RASEAPINFO structure that contains user-specific Extensible 


Authentication Protocol (EAP) information. 


Windows NT/2000: Requires Windows NT 3.1 or later. | on ae 


Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, RasDial, 
RasinvokeEapuI | 


RASDIALPARAMS 


The RASDIALPARAMS structure contains parameters that are used by RasDial to 
establish a remote access connection. 


continued) 
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(continued) 


Members 


dwSize 
Specifies the structure size, in bytes. 


szEntryName , 
Specifies a string containing the phone-book entry to use to establish the connection. 
An empty string (“’) specifies a simple modem connection on the first available 
modem port, in which case a nonempty szPhoneNumber must be provided. 


Windows NT 4.0 and later versions: The callback number is no longer stored in the 
registry. Specifying an asterisk for szCallbackNumber causes RAS to return error 
704: ERROR_BAD_CALLBACK_NUMBER. 


szPhoneNumber 
Specifies a string that contains an overriding phone number. An empty string (“’) 
indicates that the phone-book entry’s phone number should be used. If szEntryName 
| is “’, szPhoneNumber cannot be“. . 


_ szCallbackNumber | | 
Specifies a string that contains a callback phone number. An empty string ( 
indicates that callback should not be used. This string is ignored unless the user has 
“Set By Caller” callback permission on the RAS server. An asterisk indicates that the 
number stored in the phone book should be used for callback. 


szUserName 
Specifies a string that contains the user’s user name. This string is used to 
authenticate the user's access to the remote access server. 


szPassword 
Specifies a string that contains the user’s password. This string is used to 
authenticate the user’s access to the remote access server. 


Windows NT/2000: You can use szPassword to send a new password to the remote 
server when you restart a RasDial connection from a RASCS_PasswordExpired 
paused state. When changing a password on an entry that calls Microsoft Networks, 
you should limit the new password to 14 characters in length to avoid down-level 
compatibility problems. | | 


Windows 2000 and later versions: When retrieving the password using the 
RasGetEntryDialParams function, the szPassword member does not receive the 
actual password. Instead, szPassword receives a handle to the saved password. 
You can substitute this handle for the saved password in calls to RasSetDialParams, 
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and RasDial. When presented with this handle, RasDial retrieves and uses the saved 
password. The value of this handle may change in future versions of the operating 
system; do not develop code that depends on the contents or format of this value. 
szDomain | | 
Specifies a string that contains the domain on which authentication is to occur. An 
empty string (“’) specifies the domain in which the remote access server is a member. 
An asterisk specifies the onan stored in the phone book for the entry. 
dwSubEntry | 
Specifies the index of the initial subentry to dial. If the dial mode is 
RASEDM_DialAsNeeded, RAS dials this subentry. If dwSubEntry is not a valid 
subeniry index, RAS dials the first subentry. 
If the dial mode of the phone-book entry is RASEDM_ DialAll dwSubEntry is ignored. 
_ If the phone-book entry has no subentries, dwSubEntry is ignored. 


The subentry indices are one-based. That is, the first subentry has an index of one, 

the second subentry as an index of two, and so on. 

The RASENTRY structure returned by RasGetEntryProperties indicates the dial 

mode (dwDialhode) and number of subentries (dwSubEntries) for the phone-book 

entry. 

Windows 2000 and later: If dwSubErtry specifies a valid sine nie) index, RAS dials 

the specified subentry regardless of the dial mode. If the dial mode is 

RASEDM_DialAll and dwSubEntry is zero, RAS dials all of the subentries. 
dwCallbackid | 

Specifies an application-defined value that RAS passes to your RasDialFunc2 

callback function. | 


Remarks | 
The szUserName and szPassword strings are used to authenticate the user’s access 
to the remote access server. 


Windows NT/2000: RAS does not actually log the user onto the network. The user does 
this in the usual manner, for example, by logging on with cached credentials prior to 
making the connection, or by using CTRL+ALT+DEL after the RAS connection is 
established. 


If both the szUserName and szPassword members are empty strings (“"), RAS uses 
the user name and password of the current logon context for authentication. For a user- 
mode application, RAS uses the credentials of the currently logged-on interactive user. 
For a Win32 service process, RAS uses the credentials associated with the service. 


Windows 95: RAS uses the szUserName and szPassword strings to log the user onto 
the network. | 


- Windows 95 cannot obtain the password of the currently logged- -on user, So if both the 
- szUserName and the szPassword members are empty strings "); RAS leaves the 
user name and password empty during authentication. . 
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Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 


Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, RasDial, 
RasGetEntryProperties, RasSetEntryDialParams, RASENTRY 


RASEAPINFO 


The RASEAPINFO structure contains user-specific Extensible Authentication Protocol 
(EAP) information. Use RASEAPINFO to pass this information to the RasDial function. 


Members | | | 
dwSizeofEapinfo | 


Specifies the size of the binary information pointed to by the pbEapInfo member. 
pbEapInfo | 


Pointer to binary EAP information. RasDial uses this information for authentication. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasGetEapUserData, RASDIALEXTENSIONS | | 


RASEAPUSERIDENTITY | 


The RASEAPUSERIDENTITY structure stores identity information for a particular user. 


This information is required for remote access connections that use Extensible 
Authentication Protocol (EAP) for authentication. 


Chapter 8 RAS Structures 223 


Members Se | gS aa nae 


szUserName[ UNLEN + 1 ] oot 
Pointer to user name of the user requesting authentication. 


dwSizeofEapinfo | saps | 
Size of the identity information required by the extensible authentication protocol. 


pbEapInfof 1 ] 
Pointer to the identity information required by the extensible authentication protocol. 


| Remarks 


Obtain the EAP information for the current user by calling RasGetEapUserldentity. This 
function will return a RASEAPUSERIDENTITY structure containing the EAP information. 
Free the memory occupied by this structure by calling RasFreeEapUserldentity.. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
_ Header: Declared in Ras.h. 


RasFreeEapUserldentity, RasGetEapUserldentity 


RASENTRY 


The RASENTRY structure describes a phone-book entry. The RasSetEntryProperties 
and RasGetEntryProperties functions use this structure to set and retrieve the 


properties of a phone-book entry. | 


~ (continued) 
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dwSize 


Specifies the size, in bytes, of the RASENTRY structure. Before calling 


RasSetEntryProperties or RasGetEntryProperties, set dwSize to sizeof (RASENTRY) 
to identify the version of the structure. | _ 


- dwfOptions | | 
A set of bit flags that specify connection options. You can set one or more of the 


following flags. fe | ; 


Flag Description 


RASEO. If this flag is set, the dwCountrylD, dwCountryCode, and 
UseCountryAndAreaCodes szAreaCode members are used to construct the phone number. If 
this flag is not set, these members are ignored. 


This flag corresponds to the Use Country and Area Codes check 
| boxes in the Phone dialog box. 


eg eae : , (continued) 
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(continued) 
Flag | 


~ RASEO_ 
SpecificlpAddr 


RASEO_ 
SpecificNameServers 


RASEO_ 
lpHeaderCompression 


RASEO_ 


RemoteDefaultGateway 


RASEO_ | 
DisableLcpExtensions 


RASEO 
TerminalBeforeDial | 


Description | 


If this flag is set, RAS tries to use the IP address specified by ipaddr 
as the IP address for the dial-up connection. If this flag is not set, 
the value of the ipaddr member is ignored. 


Setting the RASEO_SpecificlpAddr flag corresponds to selecting the 
Specify an IP Address setting in the TCP/IP settings dialog box. 
Clearing the RASEO_SpecificlpAddr flag corresponds to selecting 
the Server Assigned IP Address setting in the TCP/IP settings 
dialog box. 


Currently, an IP address set in the phone-book entry siopaitias or 
retrieved from a server overrides the IP address set in the network 
control panel. _ 


If this flag is set, RAS uses the ipaddrDns, ipaddrDnsAlt, 
ipaddrWins, and ipaddrWinsAlt members to specify the name 
server addresses for the dial-up connection. If this flag is not set, 
RAS ignores these members. | 

Setting the RASEO_SpecificNameServers flag corresponds to 
selecting the Specify Name Server Addresses setting in the TCP/IP 
Settings dialog box. Clearing the RASEO_SpecificNameServers flag 
corresponds to selecting the Server Assigned Name Server 
Addresses setting in the TCP/IP Settings dialog box. 

If this flag is set, RAS negotiates to use IP header compression on 
PPP connections. 

If this flag is not set, IP header compression is not negotiated. 


This flag corresponds to the Use IP Header Compression check box 


_ inthe TCP/IP settings dialog box. It is generally advisable to set this 


flag because IP header compression significantly improves 
performance. The flag should be cleared only when connecting to a 
server that does not correctly negotiate IP header compression. 

If this flag is set, the default route for IP packets is through the dial- 
up adapter when the connection is active. If this flag is clear, the 
default route is not modified. 

This flag corresponds to the Use Default Gateway on Remote 
Network check box in the TCP/IP settings dialog box. — | 

If this flag is set, RAS disables the PPP LCP extensions defined in 
RFC 1570. This may be necessary to connect to certain older PPP 


implementations, but interferes with features such as server 


callback. Do not set this flag unless specifically required. 


lf this flag is set, RAS displays a terminal window for user input 
before dialing the connection. . 


Flag 


RASEO _ 
TerminalAfterDial 


RASEO_ 
ModemLights 
RASEO __ 
SwCompression 


~ RASEO_ 
RequireEncryptedPw 


RASEO_ 
RequireMsEncryptedPw 


RASEO_ | 
RequireDataEncryption 


RASEO_ 
NetworkLogon — 
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Description 


If this flag is set, RAS displays a terminal window for user input after 
dialing the connection. 

Do not set this flag if a dial-up networking script is to be associated 
with the connection, because scripting has its own terminal 
implementation. 


Windows 2000: If this flag is set, a status monitor will be displayed 


in the Task Bar. 


If this flag is set, software compression is negotiated on the link. 
Setting this flag causes the PPP driver to attempt to negotiate CCP 
with the server. This flag should be set by default, but clearing it can 
reduce the negotiation period if the server does not support a 
compatible compression protocol. 


If this flag is set, only secure password schemes can be used to 
authenticate the client with the server. This prevents the PPP driver 
from using the PAP plain-text authentication protocol to authenticate 
the client. The CHAP and SPAP authentication protocols are also 
supported. Clear this flag for increased interoperability, and set it for 
increased security. | 


_ This flag corresponds to the Require Encrypted Password check 


box in the Security dialog box. See also 
RASEO_RequireMsEncryptedPw. 


If this flag is set, only the Microsoft secure password schemes can | 
be used to authenticate the client with the server. This prevents the 
PPP driver from using the PPP plain-text authentication protocol, 
MD5-CHAP, MS-CHAP, or SPAP. The flag should be cleared for 
maximum interoperability and should be set for maximum security. © 
This flag takes precedence over RASEO_RequireEncryptedPw. 
This flag corresponds to the Require Microsoft Encrypted Password 
check box in the Security dialog box. See also 
RASEO_RequireDataEncryption. _ 

If this flag is set, data encryption must be negotiated successfuilly or. 
the connection should be dropped. This flag is ignored unless 


~RASEO_RequireMsEncryptedPw is also set. 


This flag corresponds to the Require Data eleyelion check box | in 
the Security dialog box. 


If this flag is set, RAS logs on to the network after the point-to- -point 
connection is established. : 


This i: eae has no effect under Windows NT/2000. | 
(continued) — 
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(continued) 
Flag 
RASEO_ 
UseLogonCredentials 
RASEO_ 
~ PromoteAlternates 
RASEO_ 


SecureLocalFiles 


RASEO_. 

RequireEAP 

RASEO_ 

RequirePAP 

RASEO 
RequireSPAP 
RASEO 

Custom — 

RASEO.__ 
PreviewPhoneNumber 
RASEO _ 
SharedPhoneNumbers 
RASEO _ 
ReviewUserPW 
RASEO _ 
PreviewDomain 
RASEO _ 
ShowDialingProgress 


Description 


If this flag is set, RAS uses the user name, password, and domain of 
the currently logged-on user when dialing this entry. This flag is 
ignored unless RASEO_RequireMsEncryptedPw is also set. 


Note that this setting is ignored by the RasDial function, where 
specifying empty strings for the szUserName and szPassword 
members of the RASDIALPARAMS structure gives the same result. 


This flag corresponds to the Use Current Username and Password 
check box in the Security dialog box. 


This flag has an effect when alternate phone numbers are defined 
by the dwAlternateOffset member. If this flag is set, an alternate 
phone number that connects successfully becomes the primary 
phone number, and the current primary phone number is moved to 
the alternate list. 


This flag corresponds to the check box in the Alternate Numbers 
dialog box. 


Windows NT/2000: If this flag is set, RAS checks for existing 
remote file system and remote printer bindings before making a 
connection with this entry. Typically, you set this flag on phone-book 
entries for public networks to remind users to break connections to 
their private network before connecting to a public network. 


Windows 2000: If this flag is set, an Extensible Authentication 
Protocol (EAP) must be supported for authentication. 

Windows 2000: If this flag is set, Password Authentication Protocol 
must be supported for authentication. 

Windows 2000: If this flag is set, Shiva’s Password Authentication 
Protocol must be supported for authentication. 

Windows 2000: If this flag is set, the connection will use custom 
encryption. 

Windows 2000: If this flag is set, the remote access dialer bispiays 
the phone number to be dialed. 


Windows 2000: If this flag is set, phone numbers are shared. | 


Windows 2000: If this flag is set, the remote access dialer displays 
the user’s name and password prior to dialing. 


_ Windows 2000: If this flag is set, the remote access dialer displays 


the domain name prior to dialing. 


~Windows 2000: If this flag is set, the remote access dialer displays 


its progress in establishing the connection. 
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Flag Description 
RASEO_ | Windows 2000: If this flag is set, the Challenge Handshake 
RequireCHAP Authentication Protocol must be supported for authentication. 
RASEO_ Windows 2000: If this flag is set, the Microsoft Challenge 
Require MsSCHAP _Handshake Authentication Protocol must be supported for 
| | authentication. 
RASEO_ | Windows 2000: If this flag is set, version 2 of the Microsoft 
Require MSCHAP2 | Challenge Handshake Authentication Protocol must be supported 
| | for authentication. 
RASEO_ Windows 2000: If this flag is set, MS-CHAP must send the 
RequireW95MSCHAP LanManager-hashed password. 
RASEO_ Windows 2000: If this flag is set, RAS will ae a custom-scripting 
CustomScript DLL after establishing the connection to the server. 
dwCountryiD | 


Specifies the TAP! country identifier. Use the RasGetCountryInfo function to 
enumerate country identifiers. This member is ignored unless the dwfOptions 
member specifies the RASEO_UseCountryAndAreaCodes flag. 


dwCountryCode 
Specifies the country code portion of the phone number. The country code must 
correspond to the country identifier specified by dwCountrylD. If dwCountryCode is 
zero, the country code is based on the country identifier specified by dwCountryID. 
This member is ignored unless dwfOptions specifies the | 
RASEO Se eirae abe ide Staats flag. 

szAreaCode | 

_ Specifies the area code as a null-terminated string. If the dialing location does not 
have an area code, specify an empty string (“’). Do not include parentheses or other 
delimiters in the area code string. (For example, “206” is a valid area code; “(206)” is 
not. This member is ignored unless the dwfOptions member specifies the 

RASEO_UseCountryAndAreaCodes flag. 


szLocalPhoneNumber 
Specifies a null-terminated string containing a telephone number. The way RAS uses 
this string depends on whether the dwfOptions member specifies the _ 
RASEO_UseCountryAndAreaCodes flag. If the flag is set, RAS combines - 
szLocalPhoneNumber with the country and area codes specified by the 
dwCountryID, dwCountryCode , and szAreaCode members. If the flag is not set, 
RAS uses the szLocalPhoneNumber string as the entire eee BUM EE: 


dwAlternateOffset 
Specifies the offset, in bytes, from the beginning of the structure to a list of 
consecutive null-terminated strings. The last string is terminated by two consecutive 
null characters. The strings are alternate phone numbers that RAS dials in the order 
listed if the primary number (see szLocalPhoneNumber) fails to connect. The 
alternate phone number strings are ANSI or Unicode, depending on whether you use 
the ANSI or Unicode version of the structure. 
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ipaddr 
Specifies the IP address to be used while this connection is active. This member is 
ignored unless dwfOptions specifies the RASEO se Pecile pagal flag. 

ipaddrDns | 
Specifies the IP address of the DNS server to be used while this connection is active. 
This member is ignored unless dwfOptions specifies the 
RASEO_SpecificNameServers flag. 

ipaddrDnsAlt | 

_ Specifies the IP address of a secondary or backup DNS server to be used while this 


connection is active. This member is ignored unless dwfOptions specifies the 
RASEO_SpecificNameServers flag. 


ipaddrWins 


Specifies the IP address of the WINS server to be used while this connection is 
active. This member is ignored unless dwfOptions Species the — 
~RASEO_ SpecificNameServers flag. 


ipaddrWinsAlt 


Specifies the IP address of a secondary WINS server to be used while this connection 
is active. This member is ignored unless dwfOptions specifies the 
RASEO _SpecificNameServers flag. 


_dwFrameSize 
Specifies the network protocol frame size. The value should be either 1006 or 1500. 
This member is ignored unless dwFramingProtocol specifies the RASFP_Slip flag. 
dwfNetProtocols 


specifies the network protocols to negotiate. This member can be a combination of 
the following flags. 


Flag Description 


RASNP_NetBEUI Negotiate the NetBEUI protocol. 
RASNP_|Ipx Negotiate the IPX protocol. 
~ RASNP_Ip Negotiate the TCP/IP protocol. 


dwFramingProtocol 


‘Specifies the framing protocol used by the server. PPP is the emerging standard. 
SLIP is used mainly in UNIX environments. This member can be one of the following 


flags. 

Flag Description 

RASFP_Ppp Point-to-Point Protocol (PPP) 

RASFP_Slip Serial Line Internet Protocol (SLIP) 

RASFP_Ras |” Asynchronous NetBEUI, Microsoft proprietary protocol 


implemented in Windows NT 3.1 and Windows for 
Workgroups 3.11 
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To use Compressed SLIP, set the RASFP_Slip flag and set the 
RASEO_IpHeaderCompression flag in the dwfOptions member. 


Windows 2000 or later: The RASFP_Ras flag is no longer supported. As a result, 

Windows 2000 and later computers will not be able to connect to Lan Manager, 

Windows for Workgroups 3.11, or Windows NT 3.1 servers. However, these earlier 
platforms will continue to be able to connect to Windows 2000 and later servers. 


szScript 
Specifies a null-terminated string containing the name of the script fle. The file name 
should be a full path. 


Windows NT/2000: To indicate a Windows NT/Windows 2000 SWITCH. INF script 
~ name, set the first character of the name to “{”. 


szAutodialDll 
Specifies a null-terminated string containing the full path and file name of the 
Dynamic-Link Library (DLL) for the customized AutoDial handler. lf szAutodialDIil 
contains an empty string (“’), RAS uses the default dialing user interface and the 
szAutodialFunc member is ignored. 


szAutodialFunc 
Specifies a null-terminated string containing the exported name of the RASADFunc 
function for the customized AutoDial handler. An AutoDial DLL must provide both 
ANSI and Unicode versions of the RASADFunc handler. However, do not include the 
“A” or “W” suffix in the name epee tieg by szAutodialFunc: 


szDeviceType 


Specifies a null-terminated string indicating the RAS device type referenced by 
szDeviceName. This member can be one of the following string constants. 


String Description 
RASDT_Modem A modem accessed through a COM port. 
RASDT_Isdn An ISDN card with corresponding NDISWAN driver | 
2 tei. ihe installed. | 
RASDT_X25 | An X.25 card with corresponding NDISWAN driver installed. 
-RASDT_Vpn | Windows 2000: A virtual private network connection. 
RASDT_Pad Windows 2000: A Packet Assembler/Disassembler. 
RASDT_Generic Windows 2000: Generic : 
RASDT_Serial Windows 2000: Direct serial connection through a 
aa - serial port. | ee 
RASDT_FrameRelay | Windows 2000: Frame Relay | 
RASDT_Atm Windows 2000: Asynchronous Transfer Mode 
_ RASDT_Sonet Windows 2000: Sonet © | 
_ RASDT_SW56  ~—_—sC Windows 2000: Switched 56K Access 
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(continued) 
String Description 
RASDT_Irda Windows 2000: Infrared Data Association (IrDA) compliant 
| device. 
RASDT_Parallel Windows 2000: Direct parallel connection through a 
parallel port. 


Windows 95: The RASDT_Vpn device type is supported on Windows 95 only if 
Microsoft Dial-Up Networking Version 1.2 is installed. The RASDT_X25 and 
RASDT_Pad device types are not supported on Windows 95. 


Windows 98: The RASDT_Vpn device type is supported on Windows 98. However, 
the RASDT_X25 and RASDT_Pad device types are not currently supported on 
Windows 98. 
szDeviceName 
Contains a null-terminated string containing the name of a TAPI device to use with 
this phone-book entry, for example, “XYZ Corp 28800 External’. To enumerate all 
available RAS-capable devices, use the RasEnumDevices function. 
szX25PadType | 
Contains a null-terminated string that identifies the X.25 PAD type. Set this member to 
“ unless the entry should dial using an X.25 PAD. 
Windows NT/2000: Under Windows NT/Windows 2000, the szX25PadType string 
maps to a section name in PAD.INF. — 
szX25Address | 
Contains a null-terminated string that identifies the X.25 address to connect to. Set 
this member to “ unless the entry should dial using an X.25 PAD or native X.25 
device. 
$zX25Facilities 
Contains a null-terminated string that specifies the facilities to request from the X.25 
_ host at connection. This member is ignored if szX25Address is an empty string (“’). 
szX25UserData 
Contains a null-terminated string that specifies additional connection information 
supplied to the X.25 host at connection. This member | is ignored if szX25Address is 


an empty string (*). 


dwChannels; 
dwReserved1 
Reserved; must be zero. 


dwReserved2 | = 
Reserved; must be zero. 

dwSubEntries | 
Specifies the number of multilink subentries associated with this entry. When calling 
RasSetEntryProperties, set this member to zero. To add subentries to a pew -book 
entry, use the RasSetSubEntryProperties function. 
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dwDialMode 
Specifies whether RAS should dial all of this entry’s multilink subentries when the 
entry is first connected. This member can be one of the following values. 


Value Meaning 


RASEDM_DialAll Dial all subentries initially. 


RASEDM_DialAsNeeded Adjust the number of subentries as bandwidth is 
needed. RAS uses the dwDialExtraPercent, 
dwDialExtraSampleSeconds, 
dwDialHangUpExtraPercent, and 
dwHangUpExtraSampleSeconds members to 
determine when to dial or disconnect a subentry. 


Windows 2000 and later: In order for RAS to dial all subentries, dwDialMode must 
be set to RASEDM_DialAll and the dwSubEntry member of RASDIALPARAMS must 
be set to zero. 


dwDialExtraPercent 
Windows 2000 or later: Specifies a percent of the total bandwidth available from the 
currently connected subentries. RAS dials an additional subentry when the total 
bandwidth used exceeds dwDialExtraPercent percent of the available bandwidth for 
at least dwDialExtraSampleSeconds seconds. 


This member is ignored unless the dwDialMode member Species the 
RASEDM_DialAsNeeded flag. 


dwDialExtraSampleSeconds | 
Windows 2000 or later: Specifies the number of seconds that current bandwidth | 
usage must exceed the threshold specified by dwDialExtraPercent before RAS dials 
an additional subentry. 


This member is ignored unless the dwDialMode member specifies the 
RASEDM_DialAsNeeded flag. 


dwHangUpExtraPercent 
Windows 2000 or later: Specifies a percent of the total bandwidth available from the 
currently connected subentries. RAS terminates (hangs up) an existing subentry 
connection when total bandwidth used is less than dwHangUpExtraPercent percent 
of the available bandwidth for at least dwHangUpExtraSampleSeconds seconds. 


This member is ignored unless the dwDialMode member specifies the 
RASEDM_DialAsNeeded flag. 


dwHangUpExtraSampleSeconds 
Windows 2000 or later: Specifies the number of seconds that current bandwidth 
usage must be less than the threshold specified by dwHangUpExtraPercent before 
RAS terminates an existing subentry connection. 


This member is ignored unless the dwDialMode member specifies the | 
RASEDM_DialAsNeeded flag. 
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dwidieDisconnectSeconds 
Specifies the number of seconds after which the connection is terminated due to 
inactivity. Note that unless the idle time out is disabled, the entire connection is 
terminated if the connection is idle for the specified interval. This member can specify 
a number of seconds, or one of the following values. 


Value : Meaning 

RASIDS_Disabled There is no idle time out for this connection. 

RASIDS_UseGlobalValue Use the user preference value as the default. 
dwType | 


Windows 2000: The type of phone-book entry. This member can be one of the 
following types. 


Type Description 
RASET_Phone | Phone line, for example, modem, ISDN, X.25. 
_RASET_Vpn | Virtual Private Network 
RASET_Direct Direct serial or parallel connection 
RASET_Internet Internet Connection Services (ICS) 
dwEncryptionType | | 


Windows 2000: The type of encryption to use for Microsoft Point to Point Encryption 
(MPPE) with the connection. This member can be one of the following values. 


Value — | Meaning 

ET_40Bit Require encryption 

ET_128Bit Require strong encryption 

ET_None No encryption 

ET_Require Require encryption 

ET_RequireMax Require maximum-strength encryption. 
ET_Optional Do encryption if possible. No encryption is okay. 


The value of dwEncryptionType does not affect how passwords are encrypted. 
Whether passwords are encrypted and how passwords are encrypted is determined 
by the authentication protocol, e.g. PAP, MS-CHAP, EAP. 

dwCustomAuthKey 
Windows 2000: This member is used for Extensible Authentication Protocol (EAP). 
This member contains the authentication key provided to the EAP vendor. 

guidid 


Windows 2000: The GUID (Globally Unique eee! that represents this phone- 
nook entry. This member is not settable. 
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hase rike pil eee PATH] 
Windows 2000: A null-terminated string containing the full path and file name for the 
dynamic link library (DLL) that implements the custom-dialing functions. This DLL 
should export Unicode versions of functions named RasCustomDial, 
RasCustomHangup, RasCustomEntryDlg, and RasCustomDialDlg. These 
functions should have prototypes RasCustomDialFn and RasCustomHangUpFn as 
defined in Ras.h, and RasCustomDialDigFn and RasCustomEntryDIgFn as defined in 
Rasdlg.h. 


lf szCustomDialDIl contains an empty string, RAS uses the default system dialer. 
dwVpnStrategy 


Windows 2000: The VPN strategy to use when dialing a VPN connection. This 
member can have one of the following values. , 


Value Meaning 


VS_ Default With this strategy, RAS dials PPTP first. f PPTP fails, L2TP is 
attempted. Whichever protocol succeeds is tried first in subsequent 
as dialing for this entry. ? 
VS_PptpOnly = RAS will dial only PPTP. 
VS_PptpFirst RAS will always dial PPTP first. 
VS_L2tpOnly — RAS will dial only L2TP. 
VS_L2tpFirst RAS will always dial L2TP first. 


Remarks 


‘Unless the operating system is , Windows 2000 or later, the RAS Connection Manager 
ignores the dwDialMode, dwDialExtraPercent, dwDialExtraSampleSeconds, 
dwHangUpExtraPercent, and dwHangUpExtraSampleSeconds members. RAS uses 
these members for the Bandwidth Allocation Protocol (BAP). BAP is available only on 
Windows 2000 or later versions. 


Windows 2000 and later: If the RAS client is using Bandwidth Allocation Protocol (BAP) 
_ with server callback, the registry value BapListenTimeout specifies the length of time, 
~ in seconds, the client will wait for the server to callback. This value is located beneath 
the registry key: 


HKEY_LOCAL _MACHINE\SYSTEM\CurrentControlSet\Services\RasManipop 
BapListenTimeout i is of type REG_DWORD. BapListenTimeout can be any number in 
the range 0 to OxFFFFFFFF. It has a default value of 30. 


Windows 2000 and later: If dwEncryptionType is ET_None, but : 
RASEO ee ee is glee itis as though dy Encryption ype was | 
ET fedure: 


236 Volume 4 Remote Access Services 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 OSR2 or later. 

Header: Declared in Ras.h. | | 
Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RASADFunc, RasGetCouniryinfo, RasGetEntryProperties, RasSetEntryProperties, 
RasSetSubEntryProperties 


RASENTRYDLG 


The RASENTRYDLG structure is used in the RasEntryDlg function to specify additional 
input and output parameters. 


embers 


wSize 
Specifies the size of this structure, in bytes. Before calling RasEntryDlg, set this 
member to sizeof(RASENTRYDLG) to indicate the version of the structure. If dwSize 


is not a valid size, RasEntryDlg fails and sets the dwError member to 
ERROR_INVALID_SIZE. 


wndOwner 


Specifies the window that owns the modal RasEntryDlg dialog box. This member can 
be any valid window handle, or it can be NULL if the dialog box has no owner. 


wFlags | 
A set of bit flags that indicate the options enabled for the dialog box. This parameter © 
can be a combination of the RASEDFLAG_PositionDlg flag and one of the other flags 


listed following to indicate whether the RasEntryDlg function is creating, copying, or 
editing a phone-book entry. 
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Value Meaning 


RASEDFLAG_PositionDlg Causes RasEntryDlg to use the values specified by 
the xDig and yDIg members to position the dialog 
box. If this flag is not set, the dialog box is centered on 
the owner window, unless hwndOwner is NULL, in 
which case, the dialog box is centered on the screen. 


RASEDFLAG_NewEntry Causes RasEntryDlg to display a wizard for creating 
a new phone-book entry. 


RASEDFLAG_CloneEntry Causes RasEntryDlg to create a new entry by | 
~ copying the properties of an existing entry. The 
function displays a property sheet containing the 
properties associated with the phone-book entry 
specified by the /oszEntry parameter of RasEntryDlg. 
The user can edit the properties and oe aname 
for the new entry. 


RASEDFLAG_NoRename Causes RasEntryDlg to display a property sheet for 
editing the properties of the phone-book entry 
specified by the /oszEntry parameter of RasEntryDlg. 
The user can change the properties of the entry but 
not its name. 


xDlig 
Specifies the horizontal screen coordinate of the upper-left corner of the dialog box. 
This value is used only if the RASEDFLAG_PositionDlg flag is set. 
yDig | 
Specifies the vertical screen coordinate of the upper-left corner of the dialog box. This 
value is used only if the RASEDFLAG_PositionDig flag is set. 


szEntry 
On exit, szEntry is set to the name of the phone- “book entry that was edited or 
created. 


dweError : | 
_ The RasEntryDlg function sets this member to a system error code or RAS error 
code if an error occurs. If no error occurs, the function sets dwError to zero. This 
value is ignored on input. | 
reserved 
Reserved; must be zero. 


-reserved2 .. 
Reserved; must be zero. 
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SS a 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Rasdig.h. 


Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasEntryDlg 


RASENTRYNAME 


The RASENTRYNAME structure contains an entry name from a remote access phone 
book. The RasEnumEntries function returns an array of these structures. 


Members 


dwSize 


Specifies the structure size, in bytes. Before using RASENTRYNAME in a function 
call, set this member to sizeof(RASENTRYNAME). 


szEntryName | | 
Specifies a string containing the name of a remote access phone-book entry. 


dwFlags 
Windows 2000: Specifies whether the entry is in the system phone book in the 


AllUsers profile, or in the user’s profile phone book. This member should be one of the 
following values. 3 


Value oe” Meaning 
REN_AllUsers __ The phone book is a system phone book and is in the 
AllUsers profile. — 7 - 
REN_User : The phone book is in the user’s profile. 
szPhonebookPath 3 7 


Windows 2000: Specifies the full path and file name of the Phone-Book PBK) file. 
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Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 


Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasEnumEntries 


RASIPADDR 


The RASIPADDR structure contains an IP address. The RASENTRY structure uses this 


structure to specify the IP addresses of various servers associated with an entry in a 
AS phone book. | | 


a, b, c, and 


address. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RASENTRY | | | 
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RASMONITORDLG 


The RASMONITORDLG structure is used in the RasMonitorDlg function to specify 
additional input and output parameters. 


Members 


dwSize 7 : 
Specifies the size of this structure, in bytes. Before calling RasMonitorDig, set this 
member to sizeof(RASMONITORDLG) to indicate the version of the structure. If 
dwSize is not a valid size, RasMonitorDlg fails and sets the dwError member to 
ERROR_INVALID_SIZE. | 


hwndOwner 
Specifies the window that owns the modal RasMonitorDlg property sheet. This 
member can be any valid window handle, or it can be NULL if the property sheet has 
no owner. Oo 


dwFlags 
A bit flag that indicates the options that are enabled for the property sheet. You can 
specify the following value. 


Value Meaning 


RASMDFLAG_PositionDlg Causes RasMonitorDlg to use the values specified 
by the xDIg and yDIg members to position the 
dialog box. If this flag is not set, the dialog box is 
centered on the owner window, unless hwndOwner 

| | is NULL, in which case, the dialog box is centered 
on the screen. 
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dwStartPage 


A set of bit flags that indicate the initial page of the property sheet to display on top. 
You can specify one of the following values. 


Value Meaning 
RASMDPAGE_Status Display the Status page on top. This is the default. 
~ RASMDPAGE_Summary Display the Summary page on top. 


RASMDPAGE_Preferences Display the Preferences page on top. 


xDig 
Specifies the horizontal screen coordinate of the upper-left corner of the property 
sheet. This value is used only if the RASMDFLAG_PositionDlg flag is set. 
yDig 
Specifies the Vatical screen coordinate of the upper-left corner of the property sheet. 
This value is used only if the RASMDFLAG_PositionDlg flag is set. 
dwError 
The RasMonitorDlg function sets this member to a system error code or RAS error 
code if an error occurs. If no error occurs, the function sets dwError to zero. This 
value is ignored on input. | 
reserved 
~ Reserved; must be zero. 
reserved2 
Reserved; must be zero. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Rasdlg.h. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
meereowens 


RASNOUSER 


The RASNOUSER structure is used with the RasPBDligFunc callback function to 
specify authentication credentials and other information. This structure enables dial-up 
networking operations that begin before a user has logged on. It is provided to support © 
the WinLogon application, and is not typically used by other applications. | 
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Members 
dwSize 


Specifies the size of this structure, in bytes. This member indicates the version of the 
structure. 


dwFlags | 
Reserved; must be zero. 


dwTimeoutMs 


Specifies the time, in milliseconds, before the RasPhonebookDig dialog box closes 
and returns to the caller as if the user had pressed the Close button. This feature is 
required for code that displays a window during WinLogon. If the user leaves his or. 


her terminal for some time, the dialog box closes and WinLogon reverts to the 
CTRL+ALT+DEL prompt. 


szUserName 


Specifies a null-terminated string that contains the name of the user. This string is 
used to authenticate the user’s right to access the remote access server. 


szPassword 


Specifies a null-terminated string that contains the user’s password. This string is 
used to authenticate the user’s right to access the remote access server. 


szDomain 


Specifies a null-terminated string that contains the domain on which authentication is 


to occur. An empty string (°’) specifies the domain in which the remote access server 
is a member. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Rasdig.h. 


Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasPBDigFunc, RasPhonebookDig | 


° 
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RASPBDLG | 


The RASPBDLG structure is used with the RasPhonebookDlg function to specify 
_ additional input and output parameters. 


Members , : 
| dwSize 
Specifies the size of this structure, in bytes. Before calling RasPhonebookDlig, set _ 
this member to sizeof(RASPBDLG) to indicate the version of the structure. If dwSize 


is not a valid size, RasPhonebookDilg fails and sets the dwError member to 
~  ERROR_INVALID_SIZE. 


~ hwndOwner | 
| Specifies the window that owns the modal RasPhonebookDlg dialog box. This 
member can be any valid window handle, or it can be NULL if the dialog box has no 
owner. | 


dwFlags 
A set of bit flags that indicate the options enabled for the dialog box. This parameter 
can be a combination of the following values. 


Value Meaning 
RASPBDFLAG_ Causes RasPhonebookDig to use the values specified by the 
PositionDlg === xDIg and yDig members to position the dialog box. If this flag — 


is not set, the dialog box is centered on the owner window, 
unless hwndOwner is NULL, in which case, the dialog box is 
centered on the screen. | 


RASPBDFLAG_ _ Turns on the close-on-dial option, overriding the user’s 
ForceCloseOnDial preference. This option is appropriate with features such as 
: RAS AutoDial where the user’s goal is to make a connection 
| immediately. a ee | | 
- | 7 tess ac me | | continued) 
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(continued) 
Value | Meaning 
RASPBDFLAG_ Causes the RasPBDIgFunc callback function specified by the 
NoUser pCallback member to receive a RASPBDEVENT_NoUser 
notification when the dialog box is starting up. This flag is for 
use in situations in which there is no logged-on user, as in the 
WinLogon application. Typically, applications should not use 
this flag. 
RASPBDFLAG_ Causes the default window position to be saved on exit. This 
UpdateDefaults flag is used primarily by RASPHONE.EXE and should not be 
used by typical applications. 
xDig 


Specifies the horizontal screen coordinate of the upper-left corner of the dialog box. 
This value is used only if the RASPBDFLAG_PositionDlg flag is set. 

yDig 
Specifies the vertical screen coordinate of the upper-left corner of the dialog box. This 
value is used only if the RASPBDFLAG_PositionDlg flag is set. 


dwCallbacklid 
Specifies an application-defined vale that is passed to the callback function specified 
by pCallback. You can use dwCallbackld to pass a pointer to application-specific 
context information. 


pCallback 
Pointer to a RasPBDigFunc callback function that receives notifications of user 
activity while the dialog box is open. This member can be NULL if you do not want 
notifications. 


dwError 
_ The RasPhonebookDig function sets this member to a system error code or RAS 
error code if an error occurs. If no error occurs, the function sets dwError to zero. 
This value is so he on input. 


reserved 
Reserved; must be zero. 


reserved2 
Reserved; must be zero. 


Windows NT/2000: ‘Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 

Header: Declared in Rasdlg.h. 

Unicode: Declared as Unicode and ANSI structures. 
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Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasPBDigFunc, RasPhonebookDig 


RASPPPCCP 


The RASPPPCCP structure contains information that describes the results of a 
Compression Control Protocol (CCP) negotiation. 


Members 


dwSize 
Size of the RASPPPCCP structure. Ensure that this member contains the size of the 
structure before using the structure in a function call. 


dweError | | | 3 | 
If the negotiation was unsuccessful, dwError contains the error that occurred. 


dwCompressionAlgorithm 
The compression algorithm in use by the client. The following table shows the 
possible values for this member. 


Value Meaning 
RASCCPCA_MPPC Microsoft Point to Point Compression (MPPC) 
Protocol (RFC 2118) 

RASCCPCA_STAC STAC option 4 (RFC 1974 

dwOptions | 
Specifies the compression options on the client. The following options are supported. 
Option Meaning 
RASCCPO_Compression Compression without encryption. 
RASCCPO_HistoryLess Microsoft Point to Point Encryption (MPPE) in 


stateless mode. The session key is changed after 
every packet. This mode improves performance on 
high latency networks, or networks that experience 
significant packet loss. | 


(continued) 
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(continued) 
Option Meaning 


RASCCPO_Encryption56bit MPPE using 56-bit keys. 
RASCCPO_Encryption40bit |= MPPE using 40-bit keys. 
RASCCPO_Encryption128bit | MPPE using 128-bit keys. 


The last three options are used when a connection is made over Layer 2 Tunneling 
Protocol (L2TP), and the connection uses IPSec encryption. 


dwServerCompressionAlgorithm 


The compression algorithm in use by the server. The following table shows the 
possible values for ns member. 


Value _ Meaning 

RASCCPCA_MPPC Microsoft Point to Point pombiessap (MPPC) 
: Protocol 

RASCCPCA_STAC | STAC option 4 


dwServerOptions 
Specifies the compression options on the server. The following options are supported. 


Option Meaning 
RASCCPO_Compression | Compression without encryption. | 
RASCCPO_HistoryLess Microsoft Point to Point Encryption (MPPE) in 


stateless mode. The session key is changed after 
every packet. This mode improves performance on 
high latency networks, or networks that experience 
significant packet loss. | 


RASCCPO_Encryption56bit MPPE using 56-bit keys. 
RASCCPO_Encryption4Obit MPPE using 56-bit keys. 
RASCCPO_Encryption128bit © MPPE using 56-bit keys. 


The last three options are used when a connection is made over Layer 2 BARN 
Protocol (L2TP), and the connection uses IPSec encryption. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Ras.h. 

Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasGetProjectioninfo, RASPROJECTION, RASPPPLCP 
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RASPPPIP 


The RASPPPIP structure contains the result of a PPP IP projection operation. 


The RasGetProjectioninfo function returns a RASPPPIP data structure when its 
rasprojection parameter has the value RASP_Ppplp. 


Members 


dwSize | | on 
Specifies the size of the structure, in bytes. Before calling the RasGetProjectioninfo 
function, set this member to indicate the version of the RASPPPIP structure that you 
are using. For information about earlier versions of this structure, see the following 


Remarks section. 


dwError fe gf ee 
Contains the result of the PPP control protocol negotiation. A value of zero indicates 
success. A nonzero value indicates failure, and is the actual fatal error that occurred 
during the control protocol negotiation, the error that prevented the projection from 
completing successfully. 


szlpAddress 
Contains a zero-terminated string that is the client’s IP address on the RAS 


connection. This address string has the form a.b.c.d; for example, “11.101 237.71". 


szServerlpAddress . “ 2 
Contains a null-terminated string that is the IP address of the remote PPP peer (that 
is, the server's IP address). This string is in “a.b.c.d” form. PPP does not require that 
servers provide this address, but Windows NT/Windows 2000 servers will consistently 
return the address anyway. Other PPP vendors may not provide the address. If the 


6699 


address is not available, this member returns an empty string, ”. 


dwOptions 
Windows 2000 and later: Specifies IPCP options for the local computer. Currently, 
the only option is RASIPO_VJ. This option indicates that IP datagrams sent by the 
local computer are compressed using Van Jacobson compression. 
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dwServerOptions 
Windows 2000 and later: Specifies IPCP options for the remote peer. Currently, the 
only option is RASIPO_VJ. This option indicates that IP datagrams sent by the remote 
peer (that is, received by the local computer) are compressed using Van Jacobson 
compression. 


Remarks | 7 


The szServerlpAddress member was added to the RASPPPIP structure beginning with 
Windows NT 3.51 and the initial release of Windows 95. Beginning with these systems, 
RasGetProjectioninfo will support both the current form of the structure and the old 
form without the szServerlpAddress member. Use the dwSize member to indicate _. 
which version you are using. 


For Windows NT 4.0 and earlier versions, RasGetProjectioninfo will return 
ERROR_INVALID_SIZE if dwSize specifies the current structure size. To retrieve PPP 
IP information from older systems, dwSize must specify the size of the old structure 
without the szServerlpAddress member. 


Windows NT/2000: Requires Windows NT 3.1 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. | 
Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasGetProjectioninfo, RASPROJECTION 


RASPPPLCP 


The RASPPPLCP structure contains information that describes the results of a PPP Link 
Control Protocol (LCP)/multi-link negotiation. | 
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Members 


dwSize 
Size of the RASPPPLCP structure. Ensure that this member contains the size of the 


structure before using the structure in a function call. 


fBundled 
_If this member is TRUE, the connection is composed of multiple links. Otherwise, this 


member is FALSE. 


dwError | 
If the negotiation was unsuccessful, dwError contains the error that occurred. 


dwAuthenticationProtocol | | 
The authentication protocol used to authenticate the client. This member can be one 


of the following values. | 


Value . Meaning 

RASLCPAP_PAP Password Authentication Protocol 
RASLCPAP_SPAP | Shiva Password Authentication Protocol 
RASLCPAP_CHAP Challenge Handshake Authentication Protocol 
RASLCPAP_EAP Extensible Authentication Protocol 


dwAuthenticationData | 
Provides additional information about the authentication protocol specified by the 


dwAuthenticationProtocol member. This member can be one of the following 
values. 


Value | Meaning 

RASLCPAD_CHAP_MD5 MD5 CHAP 

RASLCPAD_CHAP_MS Microsoft CHAP 

RASLCPAD_CHAP_MSV2 Microsoft CHAP version 2 
dwEapTypeld 


Provides the type ID of the extensible authentication protocol (EAP) used to 
authenticate the local computer. The value of this member is valid only if 
dwAuthenticationProtocol is RASLCPAPP_EAP. 
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dwServerAuthenticationProtocol 
The authentication protocol used to authenticate the server. See the 
dwAuthenticationProtocol member for a list of pie values. 
dwServerAuthenticationData 
Provides additional information about the authentication protocol specified by 


- dwServerAuthenticationProtocol. See the dwAuthenticationData member fora 
list of possible values. 


dwServerEapTypeld 


Provides the type ID of the extensible authentication protocol (EAP) used to 
authenticate the remote computer. The value of this member is valid only if 
dwServerAuthenticationProtocol is RASLCPAP_EAP. 


fMultilink 


If this member is TRUE, the connection supports multi-link. Otherwise, this member is 
FALSE. 


dwTerminateReason 
This member always has a value of zero. 


dwServerTerminateReason 
This member always has a value of zero. 


szReplyMessage[RAS_MaxReplyMessage] 


Pointer to a string that contains the message, if any, from the authentication fated 
success/failure packet. 


dwOptions 


Provides additional LCP options for the local computer. This member is a somibindiion 
of the following flags. 


Flag Meaning | 


RASLCPO_PFC Protocol Field Compression (see RFC 1172) 
RASLCPO_ACFC Address and Control Field Compression (see RFC 1172) 
RASLCPO_SSHF Short Sequence Number Header Format (see RFC 1990) 
RASLCPO_DES_56 DES 56-bit encryption 

RASLCPO_3_DES Triple DES Encryption 


dwServerOptions 


Provides addition LCP options for the remote computer. This member is a 
combination of the following flags. 


Flag | Meaning 


RASLCPO_PFC  _ Protocol Field Compression (see RFC 1172) 
RASLCPO_ACFC Address and Control Field Compression (see RFC 1172) 
RASLCPO_SSHF > Short Sequence Number Header Format eee RFC ek 
RASLCPO_DES_56 DES 56-bit encryption 

RASLCPO_3_DES Triple DES Encryption 
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~Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 
Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasGetProjectioninfo, RASPROJECTION, RASPPPCCP 


RASPPPIPX 


The RASPPPIPX structure contains the result of a PPP IPX projection operation. | 


The RasGetProjectioninfo function returns a RASPPPIPX data structure when its 
rasprojection parameter has the value RASP_Ppplpx. | 


- Members 
dwSize 
Specifies the size of the structure, in bytes. Before calling the ¢ RasGetProjectioninfo 
_ function, set this member to sizeof(RASPPPIPX). The function can then determine 
the version of the RASPPPIPX data structure that the caller of RasGetProjectionInfo 
is expecting. This allows backwards compatibility for compiled applications if there are 
future enhancements to the data structure. 


dwError 
Contains the result of the PPP control protocol negotiation. A value of zero indicates 
success. A nonzero value indicates failure, and is the actual fatal error that occurred 
during the control protocol negotiation, the error that prevented the projection from 
completing successfully. 


szilpxAddress 
Contains a zero- -terminated string that is the client’s IPX address on the RAS © 


connection. This address string has the form net.node; ee example 
“1234ABCD.12AB34CD56EF”. 
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Windows NT/2000: Requires Windows NT 3.1 or later. | 
Windows 95/98: Requires Windows 95 or later. 

Header: Declared in Ras.h. 

Unicode: Declared as Unicode and ANSI structures. | 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasGetProjectioninfo, RASPROJECTION 


RASPPPNBF 


: ~The RASPPPNBEF structure contains the result of a PPP NetBEUI Framer (NBF 
projection operation. 


The RasGetProjectioninfo function returns a RASPPPNBF data structure when its 
rasprojection parameter has the value RASP_PppNbf. 


Members 


dwSize 
Specifies the size of the structure, in bytes. Before calling the RasGetProjectioninfo 
function, set this member to sizeof(RASPPPNBF). The function can then determine 
the version of the RASPPPNBF data structure that the caller of 
RasGetProjectioninfo is expecting. This allows backwards compatibility for compiled 
applications if there are future enhancements to the data structure. 


dwError 
Contains the result of the PPP control protocol negotiation. A value of zero indicates 
success. A nonzero value indicates failure, and is the actual fatal error that occurred 
during the control protocol negotiation, the error that prevented the projection from 
completing successfully. 
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dwNetBiosError 


lf dwError has the value ERROR_SERVER_NOT_RESPONDING or 


ERROR_NETBIOS_ERROR, the dwNetBiosError field contains the NetBIOS error 
that occurred. For other values of dwError, this field contains zero. 


Windows 95: This member is undefined. 
szNetBiosError 


If dwError has the value ERROR_NAME_EXISTS_ON_NET, the szNetBiosError 
field contains a zero-terminated string that is the NetBIOS name that caused the 
conflict. For other values of dwError, this field contains the null string. 


szWorkStationName 


Contains a zero-terminated string that is the local workstation’s computer name. This" 


unique computer name is the closest NetBIOS equivalent to a client’s NetBEUI 
address on a remote access connection. 


bLana : os 


Specifies the NetBIOS network adapter identifier, or LANA, on which the remote 


access connection was established. This member contains the value OxFF if a 
connection was not established. 


Windows NT/2000: Requires Windows NT 3.1 or later. 


Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 


Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, | 
RasGetProjectioniInfo, RASPROJECTION 


~RASSLIP 


The RASSLIP structure contains the results of a the Serial Line Internet Protocol (SLIP) 
projection operation. 
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Members 


dwSize 


Specifies the size, in bytes, of the RASSLIP structure. Before calling the 
RasGetProjectioninfo function, set dwSize to sizeof (RASSLIP) to identify the version 


of the structure. 
dwError 
Specifies whether SLIP is configured. If dwError is zero, SLIP framing is configured. 
Otherwise, dwError is ERROR_PROTOCOL_NOT_CONFIGURED. 
szlpAddress 


A null-terminated string that contains the client’s IP address on the RAS connection. 
This address string has the form a.b.c.d; for example, “11.101.237.71". 


Remarks © 


If the RASENTRY structure for the phone-book entry used in a RAS connection specifies 
SLIP framing, you can call RasGetProjectioninfo with a RASPROJECTION of 
RASP_Slip to determine whether SLIP framing was successfully configured. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RASENTRY, RasGetProjectioninfo, RASPROJECTION 


~RASSUBENTRY 


The RASSUBENTRY structure contains information about a subentry of a RAS phone- 
book entry. The RasSetSubEntryProperties and RasGetSubEntryProperties 
functions use this structure to set and retrieve the properties of a subentry. 
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Members — 

dwSize — 
Specifies the size, in bytes, of the RASSUBENTRY structure. Before calling 
RasSetSubEntryProperties or RasGetSubEntryProperties, set dwSize to 
sizeof(RASSUBENTRY ) to identify the version of the structure. 

dwfFlags 
Currently unused. The RasSetSubEntryProperties function sets this member to 
zero. The RasGetSubEntryProperties function ignores this member. 

szDeviceType 
Specifies a null-terminated string indicating the RAS device type referenced by 
szDeviceName. This member can be one of the following string constants. 


String Description 


RASDT_Modem Amodem accessed through a COM port. 


RASDT_Isdn An ISDN card with the corresponding NDISWAN driver installed. 
RASDT_X25 An X.25 card with the corresponding NDISWAN driver installed. 
RASDT_Vpn A virtual private network connection. 

3 RASDT_ Pad A Packet Assembler/Disassembler — 


Windows 95: The RASDT_Vpn device type is supported on Windows 95 only if 
Microsoft Dial-Up Networking Version 1.2 is installed. The RASDT_X25 and 
RASDT_Pad device types are not supported on Windows 95. 


Windows 98: The RASDT_Vpn device type is supported on Windows 98. However, 
the RASDT_X25 and RASDT_Pad device types are not currently supported « on 
Windows 98 


- szDeviceName 

Specifies a null-terminated string containing the name of the TAPI device to use with 
this phone-book entry. To enumerate all available RAS- capable devices, use the 
RasEnumDevices function. 


szLocalPhoneNumber 
Specifies a null-terminated string containing a telephone number. The way RAS uses 
this string depends on whether the RASEO _ UseCountryAndAreaCodes flag is set in 
the dwfOptions member of the RASENTRY structure for this phone-book eniry. If the 
flag is set, RAS combines szLocalPhoneNumber with the country and area codes 
specified in the RASENTRY structure. If the flag is not set, RAS uses the | 
szLocalPhoneNumber string as the entire phone number. 
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dwaAlternateOffset 


Specifies the offset, in bytes, from the beginning of the structure to a list of 
consecutive null-terminated strings. The last string is terminated by two consecutive 
null characters. The strings are alternate phone numbers that RAS dials in the order 
listed if the primary number (see szLocalPhoneNumber) fails to connect. The 


alternate phone number strings are ANSI or Unicode, depending on whether you use 
the ANSI or Unicode version of the structure. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Unicode: Declared as Unicode and ANSI structures. 


Remote Access Service (RAS) Overview, Remote Access Service Structures, 
RasGetSubEntryProperties, RasSetSubEntryProperties 
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CHAPTER 9Q 


RAS Message and Enumeration 
Types 


Remote Access Service Message 


Use WM_RASDIALEVENT to implement RAS functionality. 


WM_RASDIALEVENT 


The operating system sends a WM_RASDIALEVENT message to a window procedure 
when a change of state event occurs during a RAS connection process, and a window | 
has been specified to handle notifications of such events by using the notifier parameter 
of RasDial. 


The two message parameters are equivalent to the parameters of the same names that 
are used with RasDialFunc and RasDialFunc1 callback functions. 


Parameters 


rasconnstate 
Value of wParam. Equivalent to the rasconnstate parameter of the RasDialFunc and 
RasDialFunci callback functions. Specifies a RASCONNSTATE enumerator value 
that indicates the state the RasDial remote access connection process is about to 
enter. 


dwError 
Value of /Param. Equivalent to the dwError parameter of the RasDialFunc and 
RasDialFunci callback functions. A nonzero value indicates the error that has 
occurred, or zero if no error has occurred. | 


RasDial sends this message with dwError set to zero upon entry to each connection 
state. If an error occurs within a state, the message Is sent again for the state, this 
time with a nonzero dwError value. 
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Return Values 
lf an application processes this message, it should return TRUE. 


Windows NT/2000: Requires Windows NT 3.5 or later 


Windows 95/98: Requires Windows 95 or later 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Messages, RasDial, 
RasDialFunc, RasDialFunc1, RASCONNSTATE 


Remote Access Service Enumeration Types 


RASCONNSTATE 


| The RASCONNSTATE enumeration type contains values that specify the states that 
may occur during a RAS connection operation. If you use the RasDial function to 
establish a RAS connection, you can specify a window, or a RasDialFunc, | 
| RasDialFunc1, or RasDialFunc2 callback function to receive notification messages that 


report the current connection state. You can also use the RasGetConnectStatus 
function.to get the connection state for a specified connection. 


ee 
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The enumerator values are listed here in the general order in which the connection 
states occur. However, you should not write code that depends on the order or 
occurrence of particular RASCONNSTATE connection states, because this may vary 


between platforms. a caret | 


Enumerator Value — Meaning 

RASCS_OpenPort — The communication port is about to be opened. 

RASCS_PortOpened The communication port has been opened successfully. 

RASCS_ConnectDevice A device is about to be connected. RasGetConnectStatus can 
be called to determine the name and type of the device being 

3 connected. ye oe 

RASCS_DeviceConnecte - A device has connected successfully. RasGetConnectStatus 


, can be called to determine the name and type of the device 
teu | being connected. : 


(continued) 
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(continued) 


Enumerator Value 


RASCS._ AllDevicesConnected 


RASCS_ Authenticate 


RASCS_AuthNotify 


RASCS_AuthRetry 


RASCS_AuthCallback 


Meaning 


For a simple modem connection, RASCS_ConnectDevice and 
RASCS_DeviceConnected will be called only once. For a dial- 
up X.25 PAD connection, the pair will be called first for the 


-modem, then for the PAD. If a preconnect switch is configured, 


the pair will be called for the switch before any other devices 
connect. Likewise, the pair will be called for a postconnect 
switch after any other devices connect. 


Windows 95: Note that Windows 95 does not currently support 
multistage connections such as the X.25 PAD connection 
described earlier. 


All devices in the device chain have siceasetilly connected. At 
this point, the physical link is established. 


The authentication process is starting. Remote access does not 


allow the remote client to generate any traffic on the LAN until 


authentication has been successfully completed. 


Remote access authentication on a Windows NT/ 
Windows 2000 or Windows 95 server consists of: 


e Validating the user name/password on the specified domain. 


e Projecting the client onto the LAN. This means that the 
remote access server does what is necessary to send and 
receive data on the LAN on behalf of the client. For example, 
the remote access server might need to add a NetBIOS 
name that corresponds to the client’s computer name. 


e Caill-back processing in which the client hangs up and the 
server calls back. (The user needs special permissions on 
the remote access server for this.) 


e Calculating the link speed. This is necessary to correctly set 
transport time-outs to match the evel slow speed of the 
remote link. 


An authentication event has occurred. If dwError is zero, this 
event will be immediately followed by one of the more specific 
authentication states following. If dwError is nonzero, 
authentication has failed, and the error value indicates why. 


The client has requested another validation attempt with a new 
user name/password/domain. This state does not occur in 
Windows NT version 3.1. 


The remote access server has requested a callback number. 
This occurs only if the user has “Set By Caller’ callback 
privilege on the server. 


Enumerator Value 


RASCS_AuthChangePassword 


RASCS_AuthProject 
RASCS_AuthLinkSpeed 
RASCS_AuthAck 
RASCS_ReAuthenticate 
RASCS_ Authenticated 
RASCS_PrepareForCallback 
RASCS_WaitForModemReset 


RASCS_WaitForCallback 


RASCS_Projected 


RASCS_StartAuthentication 
RASCS_CallbackComplete 
RASCS_LogonNetwork 


RASCS_SubEntryConnected 


RASCS_SubEntryDisconnected 


RASCS Interactive 


RASCS_RetryAuthentication 
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Meaning 


The client has requested to change the password on the 
account. This state does not occur in Windows NT version 3.1. 


The projection phase is starting. 

The link-speed calculation phase is starting. 

An authentication request is being acknowledged. 
Reauthentication (after callback) is starting. 

The client has successfully completed authentication. 
The line is about to disconnect in preparation for callback. 


The client is delaying in order to give the modem time to reset 
itself in preparation for callback. 

The client is waiting for an incoming call from the remote. 
access server. 

This state occurs after the RASCS_AuthProject state. It 
indicates that projection result information is available. You can 
access the projection result information by aa 
RasGetProjectioninfo. 


Windows 95 only: Indicates that user authentication is being 
initiated or retried. 

Windows 95 only: Indicates that the client has been called 
back and is about to resume authentication. © 

Windows 95 only: Indicates that the client is logging on to ae 
network. 

When dialing a multilink phone-book entry, this state indicates — 
that a subentry has been connected during the dialing process. © 


The dwSubEntry parameter of a RasDialFunc2 callback 


function indicates the index of the subentry. When the final — 
state of all subentries in the phone-book entry has been 
determined, the connection state is RASCS_Connected if one 
or more subentries have been connected successfully. 


When dialing a multilink phone-book entry, this state indicates 
that a subentry has been disconnected during the dialing 
process. The dwSubEntry parameter of a RasDialFunc2 
callback function indicates the index of the subentry. 
This state corresponds to the terminal state supported by 
RASPHONE.EXE. This state does not occur in Windows NT 
version 3.1. | 
This state corresponds to the retry authentication state — 
supported by RASPHONE.EXE. This state does not occur in 
Windows NT version 3.1. 

(continued) 
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(continued) 
Enumerator Value Meaning 


-RASCS_CallbackSetByCaller This state corresponds to the callback state supported by 


RASPHONE.EXE. This state does not occur in Windows NT 


version 3.1. 

RASCS_PasswordExpired This state corresponds to the shange password state supported 
by RASPHONE.EXE. This state does not occur in Windows NT 
version 3.1. 7 | 

RASCS_InvokeEapUI An application can use this paused state to bring up a custom 


authentication UI. The application should call the | 
RasInvokeEapuI function to invoke the custom UI. 
RASCS_InvokeEapUI is a paused state. 


RASCS_Connected Successful connection. 
RASCS_ Disconnected Disconnection or failed connection. 
Remarks 


The connection process states are divided into three classes: running states, paueee 
states, and terminal states. 


An application can easily determine the class of a specific state by performing Boolean 
bit operations with the RASCS_PAUSED and RASCS_DONE bitmasks. Here are some 
examples: 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Enumeration Types, 
RasDial, RasInvokeEapUI, RasGetConnectStatus, RasGetProjectioninfo, | 
RASCONNSTATUS 
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RASPROJECTION 


The RASPROJECTION enumeration type defines values that specify a particular 
authentication protocol or Point-to-Point Protocol (PPP) control protocol. An application 
passes a value of this type to the naegel folectonmto function to specify the protocol 
of interest. 


Each of the RASPROJECTION enumerators has a corresponding data structure; the 
RasGetProjectioninfo function returns the specified information in a structure of 


that type. 
Enumerator 
Value | Meaning . 
RASP_Amb Specifies the Authentication Message Block (AMB) authentication protocol. 


AMB is a NetBIOS-based protocol used to authenticate with downlevel remote 
access servers (all those prior to Windows NT 3.5). The corresponding data — 
structure is a RASAMB. 


RASP_PppNbf | Specifies the NetBEUI Framer (NBF) protocol. NBFCP is a PPP network 
control protocol used to negotiate the parameters necessary to ship NetBEUI 
_ packets on a WAN link. The corresponding data structure is a RASPPPNBF. 


RASP_Ppplpx Specifies the Internetwork Packet Exchange (IPX) control protocol. IPXCP is a 
| PPP network control protocol used to negotiate the parameters necessary to 
ship IPX packets on a WAN link. The corresponding data structure is a 
RASPPPIPX. 


RASP_Ppplp Specifies the Internet Protocol (IP) control protocol. IPCP is a PPP network 
7 control protocol used to negotiate the parameters necessary to ship IP packets 
on a WAN link. The corresponding data structure is a RASPPPIP. 


| RASP_PppCcp — Specifies the Compression Control Protocol (CCP). CCP enables computers 
| | using PPP to negotiate compression algorithms and parameters. The 
corresponding data structure is RASPPPCCP. 


RASP_PppLcp — Specifies the Link Control Protocol (LCP). LCP is used by computers to 
establish, modify, and terminate PPP connections. The corresponding data 
structure is RASPPPLCP. 


RASP_Slip Specifies the Serial Line Internet Protocol (SLIP). SLIP is a framing protocol 
used primarily | in UNIX environments. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Requires Windows 95 or later. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, Remote Access Service Enumeration Types, 
RasGetProjectioninfo, RASAMB, RASPPPIP, RASPPPIPX, RASPPPNBF 
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CHAPTER 10 


RAS Server Administration 
Reference 


RAS Server Administration Functions 


For Microsoft® Windows NT® 4.0, use the following functions to implement RAS Server 
Administration functionality. Microsoft® Windows® 95 does not provide RAS server 
support. 


RasAdminFreeBuffer 


The RasAdminFreeBuffer function frees memory that was allocated by RAS on behalf 
of the caller. | 


Parameters 


Pointer 
Pointer to the buffer to be freed. 


Return Values 
If the function succeeds, the return value is ERROR_SUCCESS. 


lf the function fails, the return value can be the following error code. 


Value | Meaning 


ERROR_INVALID_ PARAMETER The Pointer parameter is invalid. 


There is no extended error information for this function; do not call GetLastError. 


Remarks 


Use the RasAdminFreeBuffer function to free the buffers allocated by the 
RasAdminPortEnum and RasAdminPortGetinfo functions. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 
Library: Use Rassapi.lib. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RasAdminPortEnum, RasAdminPortGetinfo | 


RasAdminGetErrorString 


The RasAdminGetErrorString function retrieves a message string that corresponds to 
a RAS error code returned by one of the RAS server administration (RasAdmin 
functions. These message strings are retrieved from the RASMSG.DLL that is installed 
as part of RAS. 


Parameters 


Resourceld 
Specifies an error code returned by one of the RasAdmin functions. This value must 


be in the range of error codes from RASBASE to RASBASEEND that are defined in 
Raserror.h. 


loszString | | 
Pointer to a buffer that receives the error message corresponding to the specified 
error code. 


InBufSize 
Specifies the size, in characters, of the /pszString buffer. Error messages are typically 
80 characters or less; a buffer size of 512 characters is always adequate. 


Return Values es 
If the function succeeds, the return value is ERROR_SUCCESS. 


lf the function fails, the return value is an error code. This value can be a last error value 
set by the LoadLibrary, GlobalAlloc, or LoadString functions; or it can be one of the 
following error codes. 
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Value Meaning 

ERROR_INVALID_PARAM ETER The Resourceld or lposzString parameters are 
invalid. 

ERROR_INSUFFICIENT_BUFFER The size specified by the /nBufSize parameter 
is too small. 


There is no extended error information for this function; do not call GetLastError. 


Remarks 


The RasAdmin functions can return error codes that are not in the range supported by 
the RasAdminGetErrorString function. For example, the RasAdmin functions can 
return error codes that are defined in Lmerr.h and Winerror.h. Before calling 
RasAdminGetErrorString, verify that the error code is in the range RASBASE to 
RASBASEEND, as defined in Raserror.h. | | 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 
Library: Use Rassapi.lib, 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
LoadLibrary, GlobalAlloc, LoadString © | 


RasAdminGetUserAccountServer , a 


The RasAdminGetUserAccountServer function retrieves the name of the server that 
has the user account database. You can use the returned server name in the | 


RasAdminUserGetinfo and RasAdminUserSetInfo functions to get or set information 
about a specified user. | | 
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Parameters 


lpszDomain 
Pointer to a null-terminated Unicode string that contains the name of the aeiiain to 
which the RAS server belongs. This parameter can be NULL if you are running your 
RAS administration application on a Windows NT/2000 Workstation or Server that is 
not participating in a Windows NT/2000 domain. If this parameter is NULL, the 
lpszServer parameter must be non-NULL. 


loszServer 
Pointer to a null-terminated Unicode string that contains the name of the 
Windows NT/Windows 2000 RAS server. Specify the name with leading “\\” 
characters, in the form: \\servername. This parameter can be NULL if the lpszDomain 
parameter is not NULL. 


lpszUserAccountServer 
Pointer to a buffer that receives a null-terminated Unicode string containing the name 
of a domain controller that has the user account database. The buffer should be big 
enough to hold the server name (UNCLEN +1). The function prefixes the returned 
server name with leading “\\” characters, in the form: \\servername. | 


Return Values 
If the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value can be the following error code. 


Value | Meaning 


ERROR_INVALID_PARAMETER Both JoszDomain and lpszServer are NULL. 


There is no extended error information for this function; do not call GetLastError. 


Remarks 

The RasAdminGetUserAccountServer function can obtain the name of the server with 
the user accounts database given the name of the RAS server, or the name of the 
domain in which the RAS server resides. 


The /pszDomain parameter should specify a valid Windows NT/Windows 2000 domain 
name. If you are running your RAS administration application on a | 

Windows NT/Windows 2000 Server that is not participating in a 

Windows NT/Windows 2000 domain (for example, the server is in its own work group), 
then set joszDomain to NULL. In this case, the JoszServer parameter must specify the 
server name. To get the server name, call the GetComputerName function. Be sure to 
prefix the server name with the “\\” characters. 


lf the server name specified by joszServer is a stand-alone Windows NT/Windows 2000 
Server (that is, the server or workstation does not participate in a 

Windows NT/Windows 2000 domain), then the server name itself is returned in the 
lpszUserAccountServer buffer. 7 
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You can then use the name of the user account server in a call to the 


NetQueryDisplayinformation function to enumerate the users in the user account 
database. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 
Library: Use Rassapi.lib. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
GetComputerName, RasAdminUserGetinfo, RasAdminUserSetinfo 


RasAdminPortClearStatistics | 


The RasAdminPortClearStatistics function resets the counters representing the 
various statistics reported by the RasAdminPortGetinfo function in the 


RAS PORT_STATISTICS structure. The counters are reset to zero and start 
accumulating from then on. 


eS 


ad 
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Parameters 
lpszServer 
Pointer to a null-terminated Unicode string that contains the name of the 


Windows NT/Windows 2000 RAS server. Specify the name with leading “\\’ 
characters, in the form: \\servername. 


lpszPort 


Pointer to a null-terminated Unicode string that contains the name of the port on the 
server. | , : | 


Return Values 
lf the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value can be the following error code. 
Value | | Meaning 


ERROR_DEV_NOT_EXIST | The specified port is invalid. — 
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There is no extended error information for this function; do not call GetLastError. 


Remarks 

The RasAdminPortClearStatistics function clears the statistics on the server, not 
locally within the application that makes the call. This means that the statistics are also 
reset for any other application that is monitoring the specified port. 


If the /pszPort port is part of a multilink connection, RasAdminPortClearStatistics 
resets the statistics for the specified port, The function also resets the cumulative 
statistics for the multilink connection. However, the function does not effect the individual 
Statistics for other ports that are part of the multilink connection. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 
Library: Use Rassapi.lib. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RAS_PORT_STATISTICS, RasAdminPortGetinfo 


-RasAdminPortDisconnect 


The RasAdminPortDisconnect function disconnects a port that is currently in use. 


Parameters 


lpszServer 
Pointer to a null-terminated Unicode string that contains the | name of the 
Windows NT/Windows 2000 RAS server. Specify the name with leading “\\” 
characters, in the form: \\servername. 


lpszPort 
Pointer to a null -terminated Unicode string that contains the name of the Sort on the 
server. 


Return Values | | 
If the function succeeds, the return value is ERROR_SUCCESS. 
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If the function fails, the return value can be one of the following error codes. 


Value | Meaning 
ERROR_INVALID_PORT The specified port is invalid. 
NERR_UserNotFound | The port is not currently in use. 


There is no extended error information for this function; do not call GetLastError. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 
Library: Use Rassapi.lib. 
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RasAdminPortEnum 


The RasAdminPortEnum function enumerates all ports on the specified RAS server. 
For each port on the server, the function returns a RAS PORT_0 structure that contains 
information about the port. | 


Parameters 
-_IpszServer 
Pointer to a null-terminated Unicode string that contains the name of the 
Windows NT/Windows 2000 RAS server. Specify the name with leading “\\” 
characters, in the form: \\servername. 


ppRasPort0 
Pointer to a variable that receives a pointer to a buffer that contains an array of 
RAS_PORT_0 structures. When your application has finished with the memory, free it 
by calling the RasAdminFreeBuffer function. 


pcEntriesRead 
Pointer to a 16-bit variable that receives the total pumbe of RAS_ PORT _ 0 structures © 
returned in the ppRasPort0 array. 
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Return Values 
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RasAdminPortGetinfo 


The RasAdminPortGetinfo function retrieves information about a specified port on a 


specified server. 
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Parameters 

lpszServer 
Pointer to a null-terminated Unicode string that contains the name of the 
Windows NT/Windows 2000 RAS server. ey the name with leading “\\” 
characters, in the form: \\servername. 


loszPort 
Pointer to a null-terminated Unicode string that contains the name of the port on the 
server. 

pRasPort1 
Pointer to a RAS_PORT_1 structure that the function fills in with information about the 
state of the port. 

pRasStats | 
Pointer to a RAS_PORT_STATISTICS structure that the function fills in with statistics 
about the port. 

ppRasParams 
Pointer to a variable that receives a pointer to an array of RAS_ PARAMETERS 
structures. Each structure contains the name of a media-specific key, such as 
MAXCONNECTBPS, and its associated value. When your application is finished with 
the memory pointed to by Pelsereraie, free it by calling the RasAdminFreeBuffer 
function. 


Return Values 
If the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value can be one of the following error codes. 


Value Meaning 

ERROR_DEV_NOT_EXIST The specified port is invalid. 

ERROR_NOT_ENOUGH_MEMORY Insufficient memory to allocate a buffer for the ~ 
ppRasParams array. | 


There is no extended error information for this function; do not call GetLastError. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 
Library: Use Rassapi.lib. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RAS_PARAMETERS, RAS_PORT_1, RAS_ PORT_ STATISTICS, 
RasAdminFreeBuffer 
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RasAdminServerGetinfo 


The RasAdminServerGetinfo function gets the server configuration of a RAS server. 


Parameters 


lpszServer 
Pointer to a null-terminated Unicode string that contains the name of the 
Windows NT/Windows 2000 RAS server. If this parameter is NULL, the function 
returns information about the local computer. Specify the name with leading “\\” 
characters, in the form: \\servername. 


pRasServer0 | 
Pointer to a RAS_SERVERF_0 structure that receives the number of ports configured 
on the server, the number of ports currently in use, and the server version number. 


Return Values a 
If the function succeeds, the return value is ERROR_SUCCESS. 


lf the function fails, the return value is an error code. Possible error codes include those 
returned by GetLastError for the CallNamedPipe function. There is no extended error 
information for this function; do not call GetLastError. 


Remarks 


To enumerate all RAS servers in a Windows NT/Windows 2000 domain, call the 
NetServerEnum function and specify SV_TYPE_DIALIN for the servertype parameter. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 
Library: Use Rassapi.lib. 


at 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
NetServerEnum, RAS_SERVER_0 | 
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RasAdminUserGetinfo 


The RasAdminuUserGetinfo function gets the RAS permissions and callback phone 
number information for a specified user. 


Parameters 


lpszUserAccountServer | 
Pointer to a null-terminated Unicode string that contains the name of the primary or 
backup domain controller that has the user account database. Use the 
RasAdminGetUserAccountServer function to get this server name. 
loszUser ee | | 
Pointer to a null-terminated Unicode string that contains the name of the user for 
whom to get RAS information. 


pRasUser0 | 3 
Pointer to a RAS_USER_0 siructure that receives the RAS data for the specified 
user. | | | 


Return Values 
If the function succeeds, the return value is ERROR SUCCESS. 


If the function fails, the return value can be the following error code. 


Value Paes, _ Meaning 


NERR_BufTooSmalt Insufficient memory to perform this function. 


There is no extended error information for this function; do not call GetLastError. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 
Library: Use Rassapi.lib. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RAS_USER_0, RasAdminGetUserAccountServer, RasAdminUserSetinfo 


276 Volume 4 Remote Access Services 


RasAdminUserSetinfo 


The RasAdminUserSetinfo function sets the RAS permissions and call-back phone 
number for a specified user. 


IpszUserAccountServer 
Pointer to a null-terminated Unicode string that contains the name of the primary or 
backup domain controller that has the user account database. Use the 
RasAdminGetUserAccountServer function to get this server name. 


loszUser 
Pointer to a null-terminated Unicode string that contains the name of the user for 
whom RAS information is to be set. 


pRasUser0 | 7 . 
Pointer to a RAS_USER_0 structure that contains the new RAS data for the specified 
user. | 


Return Values 
lf the function succeeds, the return value is ERROR_SUCCESS. 


If the function fails, the return value can be one of the following error codes. 


Value 3 | Description 

ERROR_INVALID_DATA The pRasUser0 buffer contains invalid data. 
ERROR_INVALID_CALLBACK_ The callback number specified in the pRasUser 
NUMBER buffer contains invalid characters. 
NERR_BufTooSmall Insufficient memory to perform this function. 


There is no extended error information for this function; do not call GetLastError. 


Remarks 


When setting the RAS permissions for a user, the bfPrivilege member of the 
RAS_USER_0 structure must specify at least one of the call-back flags. For example, to 
set a user’s privileges to allow dial-in privilege but no call-back privilege, set bfPrivilege 
to RASPRIV_DialinPrivilege | RASPRIV_NoCallback. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 
Library: Use Rassapi.lib. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RAS_USER_0, RasAdminGetUserAccountServer, RasAdminUserGetinfo 


RAS Administration DLL Functions 


Implement the following functions when developing a RAS administration DLL: 


RasAdminAcceptNewConnection 
RasAdminConnectionHangupNotification 
_ RasAdminGetipAddressForUser 
~ RasAdminReleaselpAddress 


-RasAdminAcceptNewConnection 


The RasAdminAcceptNewConnection function i is an application- -defined function that 
is exported by a third-party RAS server administration DLL. RAS calls this function when 
a user tries to establish a remote connection to a RAS server. The function decides 
whether the user is allowed to connect. | 


The RAS server calls RasAdminAcceptNewConnection once for each port ina 
multilink connection. 


Parameters 
pRasPort1 
Pointer toa RAS_PORT_1 structure that contains RAS data about the dating 


connection. This structure contains the relevant connection information that you need 
to make a decision about the connection. 
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pRasStats 
Pointer to a RAS _ PORT_ STATISTICS structure that contains statistics soil the 
port. 


pRasParams 
Pointer to an array of RAS_- PARAMETERS structures. Each structure contains the 
name of a media-specific key, such as MAXCONNECTBPS, and its associated value. 


Return Values 
If the function returns TRUE, RAS accepts the new connection. 


If the function returns FALSE, RAS does not accept the new connection. There is no 
extended error information for this function; do not call GetLastError. 


Remarks 


The RasAdminAcceptNewConnection function gives more control to a RAS server 
administration DLL to determine whether a specified remote user should be allowed to 
connect to a server. 


An additional application of RasAdminAcceptNewConnection would be to send a 
popup message to newly connected clients. Use the NetMessageBufferSend function — 
to send the message to the client computer. — | ) 


The setup program for a third- -party RAS administration DLL must register the DLL with — 
RAS by providing information under the following key in the registry: 


HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIll 


To register the DLL, set the following values under this key. 


Value name Value data 

DisplayName A REG_SZ string that contains the user-friendly display name of 
the DLL. 

DLLPath OA REG_SZ string that contains the full path of the DLL. 


For example, the registry entry for a RAS administration DLL from a fictional company 
named Netwerks Corporation might be: . 


HKEY_ LOCAL. MACHINE\SOFTWARE\Microsoft\RAS\AdminDIil 
DisplayName : REG_SZ : Netwerks RAS Admin DLL 
DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll 


The setup program for a RAS administration DLL should also provide i raercinineiall 
functionality. If a user removes the DLL, the setup program should delete the DLL’s 
registry entries. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, | 
RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS | 


RasAdminConnectionHangupNotification 
The RasAdminConnectionHangupNotification function is an application-defined — 
function that is exported by a third-party RAS server administration DLL. When RAS 


disconnects an existing connection, it calls this function to notify your DLL. 


on 


The RAS server calls RasAdminConnectionHangupNotification once for each port in 
a multilink connection. 


Parameters 


pRasPort1 
Pointer to a RAS_PORT_1 structure that contains RAS data about the connection 
that ended. This structure contains the relevant connection information that you can 
use to determine how long the port was connected. | 


pRasStats | | 

_ Pointer to a RAS_PORT_STATISTICS structure that contains statistics about the 
port. RAS began accumulating these statistics when the connection was first 
established. _ | ae ee - 

pRasParams | rs ae | , | 

_ Pointer to an array of RAS_PARAMETERS structures. Each structure contains the 
name of a media-specific key, such as MAXCONNECTBPS, and its associated value. 
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Return Values 


The function does not return a value. There are no extended error information for this 
function; do not call GetLastError. 


Remarks 


The RAS call to the RasAdminConnectionHangupNotification function is just a 
notification; no action is required from your DLL. You can use the information provided 
by this function for accounting purposes. 


The setup program for a third-party RAS administration DLL must register the DLL with 
RAS by providing information under the following key in the registry: 


HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIl 


To register the DLL, set the following values under this key. 


Value name | Value data 

DisplayName A REG_SZ string that contains the user-friendly display name of 
. the DLL. 

DLLPath A REG_SZ string that contains the full path of the DLL. 


For example, the registry entry for a RAS administration DLL from a fictional company 
named Netwerks Corporation might be: 


HKEY_LOCAL_MACHINE\SOFTWARE\icrosoft\RAS\AdminDIl 
DisplayName : REG_SZ : Netwerks RAS Admin DLL 
~DLLPath : REG_ SZ : C:\nt\system32\ntwkadm.dll 


The setup program for a RAS administration DLL should also provide remove/uninstall 
functionality. If a user removes the DLL, the setup program should delete the DLL’s 
registry entries. 


wanes puuatanioats span 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RAS_PARAMETERS, RAS_PORT_1, RAS_PORT_STATISTICS 
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RasAdminGetipAddressForUser 


The RasAdminGetlpAddressForUser function is an application-defined function that is 
exported by a third-party RAS server administration DLL. RAS calls this function to get 
an IP address for the dialed-in remote client. 


Parameters 


IpszUserName 
Pointer to a null-terminated Unicode string that contains the name of the remote user 
for whom an IP address is required. © 


loszPortName 
Pointer to a null-terminated Unicode string that contains the name of the port on which 
the user specified by /oszUserName is attempting to connect. 


pipAddress 
Pointer to an IPADDR variable. On input, *pipAddress contains either zero or the IP 
address that the RAS server proposes to use for the dialed-in remote client. The 
function can set *pipAddress to a different IP address, or accept the passed-in IP 
address. If *pipAddress is zero on input, the function must provide an IP address; 
otherwise, the client will be unable to connect to this server using IP. 


bNotifyRelease 
Pointer to a BOOL variable. Set this variable to TRUE if you want RAS to call your 
RasAdminReleaselpAddress function when the user disconnects from this port; 
otherwise, set it to FALSE. 


Return Values: 


If pip Address points to an IP address that the client can use to connect to this RAS 
server, the function should return NO_ERROR. This can occur if the function accepts the 
IP address that was passed by the RAS server, or if the function provides a different IP 
address. 


lf pipAddress does not point to an IP address, the function should return a nonzero error 
code. This can occur if no IP address is available, or if the passed in IP address is 
unacceptable. In this case, the client will be unable to connect to this server using IP. 
There is no extended error information for this function; do not call GetLastError. 
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Remarks 


The setup program for a third-party RAS administration DLL must register the DLL with 
RAS by providing information under the following key in the registry: 


HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIil 


To register the DLL, set the following values under this key. 


Value name Value data 

DisplayName A REG_SZ string that contains the user-friendly display name of 
the DLL. 

DLLPath A REG_SZ string that contains the full path of the DLL. 


For example, the registry entry for a RAS administration DLL from a fictional company 
named Netwerks Corporation might be: 


HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIil 
DisplayName : REG_SZ : Netwerks RAS Admin DLL 
DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll 


The setup program for a RAS administration DLL should also provide remove/uninstall 
functionality. If a user removes the DLL, the setup program should delete the DLL’s 
registry entries. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
‘Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RasAdminReleaselpAddress 


RasAdminReleaselpAddress 


The RasAdminReleaselpAddress function is an application-defined function that is 
exported by a third-party RAS server administration DLL. RAS calls this function to notify 
your DLL that the remote client was disconnected and that the IP address should be 
released. | | 
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Parameters 

lpszUserName 
Pointer to a null-terminated Unicode string that contains the name of a remote user for 
whom an IP address was previously obtained using the | 
RasAdminGetlipAddressForUser function. 

loszPortName 
Pointer to a null-terminated Unicode string that contains the name of the port on which 
the user specified by IlpszUserName | is connected. 

pipAddress 3 
Pointer to an IPADDR variable that contains the IP address returned for this user ina | 
previous call to RasAdminGetlpAddressForUser. 


Return Values 
There is no extended error information for this function; do no call GetLastError. 


Remarks 

The RAS server calls your RasAdminReleaselpAddress function onli if your 
application returned TRUE in the bNotifyRelease parameter during the earlier call to 
RasAdminGetIpAddressForUser for the user ee by the ipscUsoNane 
parameter. | 


The setup program for a third-party RAS administration DLL must register the DLL with 
RAS by providing information under the following key in the registry: 


H KEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIl 


To register the DLL, set the following values under this key. 


Value name Value data 
DisplayName | A REG_SZ string that contains the user- menaly display name of 
| | the DLL. 
| DLLPath A REG_SZ string that contains the full path of the DLL. 


For example, the registry entry for a RAS administration DLL from a fictional company 
named Netwerks Corporation might be: 


~ HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIl 
DisplayName : REG_SZ : Netwerks RAS Admin DLL 
DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll 


The setup program for a RAS administration DLL should also provide remove/uninstall 
functionality. If a user removes the DLL, the setup program should delete the DLL’s 
registry entries. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


| ‘Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RasAdminGetlpAddressForUser 


RAS Security DLL Functions sy. 


Implement the following functions when developing a RAS security DLL: 


asSecurityDialogBegin 
asSecurityDialogComplete 
asSecurityDialogEnd 

as lalogGetinfo | 
asSecurityDialogReceive 
asSecurityDialogSend 
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RasSecurityDialogBegin : 


The RasSecurityDialogBegin function is a third-party RAS security DLL entry point that 
the Windows NT/Windows 2000 RAS server calls when a remote user tries to connect. 
This enables the security DLL to begin its authentication of the remote user. 


Note that Windows NT/Windows 2000 currently provides RAS security host support only 
for serial devices; other types of connections, such as ISDN or a virtual private network — 
(VPN) connection, are not supported. 
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Parameters 

hPort. 
Specifies a RAS port handle. The security DLL uses this handle in other RAS security 
functions, such as RasSecurityDialogSend and RasSecurityDialogReceive, to 
identify this authentication transaction. | 


Note that this handle is valid only in RAS security functions; you cannot use it in other 
Win32 I/O functions. 


— pSendBuf 

Pointer to a buffer allocated by the RAS server. The security DLL uses this buffer with 
the RasSecurityDialogSend function to send text that is displayed in the RAS 
terminal window on the remote computer. 


SendBufSize 
Specifies the size, in bytes, of the pSendBuf buffer. 


pRecvBuf 
Pointer to a buffer allocated by the RAS server. The security DLL uses this buffer with 
the RasSecurityDialogReceive function to receive the response from the remote 
user. 


RecvBufSize | 
Specifies the size, in bytes, of the pRecvBuf buffer. 


_ RasSecurityDialogComplete 

Specifies a pointer to a RasSecurityDialogComplete function. When the security 
DLL has completed the authentication of the remote user, it calls this function to 
report the results to the RAS server. 


Return Values 

lf the security DLL successfully starts the authentication operation, 
RasSecurityDialogBegin should return NO_ERROR. In this case, the security DLL 
must later terminate the authentication transaction by calling the function Pouce to by 
the RasSecurityDialogComplete parameter. 


lf an error occurs, RasSecurityDialogBegin should return a nonzero error code. In this 
case, the RAS server hangs up the call and records the error in the | 

Windows NT/Windows 2000 event log. Returning a nonzero error code terminates the 
authentication transaction, so the security DLL does not need to call the 
RasSecurityDialogComplete function. 


Remarks | 

When a Windows NT/Windows 2000 RAS server receives a call from a remote 
computer, it calls the RasSecurityDialogBegin function exported by the registered RAS 
security DLL, if there is one. When the RAS server Calls this function, it passes the 
following information to the security DLL. — 
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e A port handle to identify the connection | 
e Pointers to buffers to use when communicating with the remote user 


e A pointer to a RasSecurityDialogComplete function to call when the authentication 
has been completed 


The port handle and buffer pointers are valid until you call RasSecurityDialogComplete 
to terminate the authentication transaction. | 


Your RasSecurityDialogBegin implementation must return as soon as possible, 
because the RAS server is blocked and cannot accept any other calls until 
RasSecurityDialogBegin returns. The RasSecurityDialogBegin function should copy 
the input parameters and create a thread to communicate with and authenticate the 
remote user. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rasshost.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RasSecurityDialogComplete, RasSecurityDialogReceive, RasSecurityDialogSend 


-RasSecurityDialogComplete 


The RasSecurityDialogComplete function notifies the RAS server of the results of a 
third-party security authentication transaction. A third-party RAS security DLL calls 
RasSecurityDialogComplete when it has completed its authentication of the remote 
user, 


The RAS server passes a pointer to the RasSecurityDialogComplete function when the 
server calls the RasSecurityDialogBegin entry point of the security DLL. 


_ Parameters 


pSecMsg — 
Pointer to a SECURITY. MESSAGE structure that contains the results of the © 
authentication transaction. — 
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Return Values 
None. 


Remarks 

When a security DLL has finished authenticating the remote user, it calls the 
RasSecurityDialogComplete function to report the results. The RAS server then 
performs a cleanup sequence. As part of this cleanup sequence, the RAS server calls 
the security DLL’s RasSecurityDialogEnd function to give the DLL an opportunity to 
perform its own cleanup, if necessary. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 

Header: Declared in Rasshost.h. 

Library: Included as a resource in Rasman.dll. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, | 
RasSecurityDialogBegin, Hass ecUtyE Eooromnrer RasSecurityDialogEnd, 
SECURITY_MESSAGE 


--RasSecurityDialogEnd — 


The RasSecurityDialogEnd function is a third-party RAS security DLL entry point that 
the Windows NT/Windows 2000 RAS server calls to terminate an cit a Se 


transaction. 


Parameters 

hPort 
Specifies the port handle that the RAS server passed to the security DLL in the 
Ras security DialogBeg!n call for this authentication transaction. 


| Return Values | | 
‘Ifthe security DLL returns NO_ERROR, the RAS server does not terminate the 
authentication transaction. In this case, the security DLL must later call the 
RasSecurityDialogComplete function when it is ready to terminate. 
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lf the security DLL returns a nonzero error code, the RAS server terminates the 
authentication transaction. In this case, the security DLL does not need to make another 


RasSecurityDialogComplete call. You should return an error code defined in 
Winerror.h or Raserror.h, such as ERROR_PORT_DISCONNECTED. 


Remarks 


When a security DLL has finished authenticating the remote user, it calls the 
RasSecurityDialogComplete function. The RAS server then performs a cleanup 
sequence that includes a call to the DLL’s RasSecurityDialogEnd function. This gives 
the security DLL an opportunity to perform any necessary cleanup. To terminate the 
authentication transaction, RasSecurityDialogEnd must return a nonzero error code. 


The RAS server may also call RasSecurityDialogEnd if it needs to abnormally 
terminate the authentication transaction before the security DLL calls 
RasSecurityDialogComplete. In this case, the security DLL should terminate the 
worker thread associated with the hPort port handle, and perform any other necessary 
cleanup. If RasSecurityDialogEnd returns a nonzero value, the security DLL does not 
need to call RasSecurityDialogComplete. 


For either a normal or abnormal termination, your RasSecurityDialogEnd function can 
return NO_ERROR to delay the termination. If it does so, it must later call 
RasSecurityDialogComplete when it is ready to terminate. | 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rasshost.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
RasSecurityDialogBegin, RasSecurityDialogComplete 


RasSecurityDialogGetInfo 


The RasSecurityDialogGetinfo function is called by a RAS security DLL to get 
information about a port from the RAS server. 


To call this function, you must first call the LoadLibrary function to load RASMAN.DLL. 
Then call the GetProcAddress function to get the DLL’s RasSecurityDialogGetInfo 
entry point. 
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Parameters 

hPort | 
Specifies the port handle that the RAS server passed to the security DLL in the 
RasSecurityDialogBegin call for this authentication transaction. 

pBuffer | | 
Pointer to a RAS_SECURITY_INFO structure that receives information about the 
specified RAS port. 


Return Values 
If the function succeeds, the return value is NO_ERROR. 


If the function fails, the return value is one of the error codes defined in Raserror.h or 
_ Winerror.h. GetLastError does not provide extended error information. 


Remarks 


The RasSecurityDialogGetinfo function retrieves information about the port associated 
with a RAS security DLL authentication transaction. 


The LastError member of the RAS_SECURITY_INFO structure indicates the state of 
the last RasSecurityDialogReceive call for the port. If the receive operation has been 
completed successfully, LastError is SUCCESS and the BytesReceived member 
indicates the number of bytes received. Otherwise, LastError is PENDING if the receive 
operation is still in progress, or a nonzero error code if the receive operation failed. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 

Header: Declared in Rasshost.h. 

Library: Included as a resource in Rasman.dll. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
GetProcAddress, LoadLibrary, RAS_SECURITY_INFO, RasSecurityDialogReceive 


RasSecurityDialogReceive 


The RasSecurityDialogReceive function starts an asynchronous operation that 
receives a remote user’s response to a security challenge. The response is the input that 
the user typed in a terminal window on the remote computer. A third-party RAS security 
DLL calls this function as part of its authentication of the remote user. 
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To call this function, you must first call the LoadLibrary function to load RASMAN.DLL. 
Then call the GetProcAddress function to get the DLL’s RasSecurityDialogReceive 
entry point. 


Parameters 


hPort 
Specifies the port handle that the RAS server passed to the security DLL in the 
RasSecurityDialogBegin call for this authentication transaction. 


pBuffer 
Pointer to the receive buffer that was passed to the security DLL in the 
RasSecurityDialogBegin call. When the asynchronous receive operation has been 
completed successfully, this buffer contains the response from the remote user. 


pBufferLength 

Pointer to a WORD variable. On input, this variable must specify the size, in bytes, of 
the pBuffer buffer. When the receive operation has been completed, the variable 
indicates the number of bytes returned in the pBuffer buffer. 


imeout 3 | 
Specifies a time-out period, in seconds, after which the RAS server sets the hEvent 
event object to the signaled state. 


lf this value is zero, there is no time-out period; that is, the RAS server does not signal 
the event object until the receive operation has been completed. 


Event 
Specifies the handle of an event object created by the CreateEvent function. The 
RAS server sets the event object to the signaled state when the receive operation has 
been completed or when the time-out period has elapsed. 


Return Values 


If the function is successful, the return value is PENDING (defined in Raserror.h). This 
indicates that the receive operation is in progress. | 


If an error occurs, the return value is one of the error codes defined in Raserror.h or 
Winerror.h. GetLastError does not provide extended error information. 
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Remarks 


After calling the RasSecurityDialogSend function to send a security challenge to the 
remote user, the security DLL must call the ores function to get 
the user’s response. 


The RasSecurityDialogReceive function is asynchronous. When the function returns, 
the security DLL must use one of the wait functions, such as WaitForSingleObject, to 
wait for the hEvent event object to be signaled. The RAS server signals the event object 
when the receive operation has been completed or when the time-out interval has 
elapsed. If the receive operation is successful, the oBuffer buffer contains the response 
from the remote user, and the pBufferLength parameter indicates the number of bytes 
received. If the remote user sends more bytes than will fit in the buffer, the RAS server 
buffers the excess bytes and returns them in the next RasSecurityDialogReceive call. 


You can use the Timeout parameter to specify a time-out interval. If the time-out 
elapses, the RAS server signals the event object, and the pBufferLength parameter 
indicates that zero bytes were transferred. Alternatively, you can set Timeout to zero, 
and specify a time-out interval in the wait function that you use to wait for the event 
object to be signaled. 


When a security DLL is authenticating a remote user, the connection operation on the 
remote computer enters a RASCS_ Interactive paused state. The message sent by 
RasSecurityDialogSend is displayed as output in a terminal window on the remote 
computer. The response received by RasSecurityDialogReceive is the input that the 
remote user types in the terminal window. The RASCS_ Interactive value is defined in the 
RASCONNSTATE enumeration. 


- Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. | 
Header: Declared in Rasshost.h. 

Library: Included as a resource in Rasman.dll. 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
CreateEvent, GetProcAddress, LoadLibrary, RASCONNSTATE, 
dieser reesei WaitForSingleObject 


‘RasSecurityDialogSend 


The RasSecurityDialogSend function sends a message to be displayed in a terminal 
window on a remote computer. A third-party. RAS security DLL sends this message as 
part of its auienteaion of a remote user. | | 
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To call this function, you must first call the LoadLibrary function to load RASMAN.DLL. 
Then call the GetProcAddress function to get the DLL’s RasSecurityDialogSend entry 
point. 


Parameters 


hPort | 
Specifies the port handle that the RAS server passed to the security DLL in the 
RasSecurityDialogBegin call for this authentication transaction. 


pBuffer 
Pointer to the send buffer that was passed to the security DLL in the call to 
RasSecurityDialogBegin. Before calling RasSecurityDialogSend, copy into this 
buffer the message to send to the remote user. The SendBufSize parameter of the 
RasSecurityDialogBegin function indicates the maximum number of bytes you can 
copy to this buffer. 


BufferLength 
Specifies the number of bytes to send in the pBuffer buffer. 


Return Values 


If the function is successful, the return value is PENDING (defined in Raserror.h). This 
indicates that the send operation is in progress. 


lf an error occurs, the return value is one of the error codes defined in Raserror.h or 
Winerror.h. GetLastError does not provide extended error information. 


Remarks 


The RasSecurityDialogSend function is asynchronous. After calling it to senda 
message to the remote user, call the RasSecurityDialogReceive function, and then 
wait for a response. The security DLL can make any number of 
RasSecurityDialogSend calls, with each call followed by a RasSecurityDialogReceive 
call. 


When a security DLL is authenticating a remote user, the connection operation on the 
remote computer enters a RASCS_Interactive paused state. The message sent by 
RasSecurityDialogSend is displayed as output in a terminal window on the remote 
computer. The response received by RasSecurityDialogReceive is the input that the 
remote user types in the terminal window. The RASCS_Interactive value is defined in the 
RASCONNSTATE enumeration. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 

Header: Declared in Rasshost.h. 

Library: Included as a resource in Rasman.dll. 


oy 


Remote Access Service (RAS) Overview, RAS Server Administration Functions, 
GetProcAddress, LoadLibrary, RASCONNSTATE, RasSecurityDialogBegin, 
RasSecurityDialogReceive 


RAS Server Administration Structures 


For Windows NT version 4.0, use the following structures to implement RAS Server 
Administration functionality. Windows 95 does not provide RAS server support. 


RAS_PARAMETERS RAS_PPP_NBFCP_RESULT 
RAS_PORT_0 | RAS_PPP_PROJECTION_RESULT 
RAS_PORT_1 RAS_SECURITY_INFO 
RAS_PORT_STATISTICS RAS_SERVER_0 
RAS_PPP_ATCP_RESULT RAS_STATS 
RAS_PPP_IPCP_RESULT RAS_USER_0 
RAS_PPP_IPXCP_RESULT SECURITY_MESSAGE 


RAS PARAMETERS 


The RAS_PARAMETERS structure is used by the RasAdminPortGetinfo function to 
return the name and value of a media-specific parameter associated with a port on a 
Windows NT/Windows 2000 RAS Server. 


Members 


P_Key A } : | | ae 
Specifies the name of the key that represents the media-specific parameter, such as 
MAXCONNECTBPS. | | 
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P_Type 
Identifies the type of data associated with the parameter. This member can be one of 
the following values from the RAS_PARAMS _ eo enumeration. | 


Value Meaning 
ParamNumber | Indicates that the data associated with the key is a number. 
ParamString Indicates that the data associated with the key isa string. 
P_ Attributes | 
Reserved. 
P_Value 


Specifies the value associated with the parameter. This member is a 
RAS_PARAMS_VALUE union. If the P_Type member is ParamNumber, the NUMBOE 
member of the union contains the value. If P_Type is ParamString, the String 
member of the union contains the value. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RasAdminAcceptNewConnection, RasAdminConnectionHangupNotification, 
RasAdminPortGetinfo 


RAS_ PORT_0 


The RAS_ PORT_0 structure contains information that describes a RAS port. 
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Members 
wszPortName ~ 
A null-terminated Unicode string that specifies the name of the port, such as “COM1”. 


wszDeviceType 
A null-terminated Unicode string that specifies the type of the device on which the 
connection was made, such as “Modem” or “ISDN”. The list of device types that might 
be specified in this member includes all the device types installed on the server, 
including third-party devices. | 
wszDeviceName 
A null-terminated Unicode string that specifies the name of the device on which the 
connection was made, such as “Hayes 9600” or “PCIMACISDN1”. 
wszMediaName — 
A null-terminated Unicode string that specifies the name of the media used for the 
connection, such as “rasser’ or “rastapi’. 
reserved 
This member is reserved. 
Flags : 
A set of bit flags that specify the nature of the connection made on this port. This 
member can be a combination of the following flags. 


Value | Meaning | 
GATEWAY_ACTIVE If this flag is set, the NetBIOS gateway is active c on 
| the server. 


MESSENGER_PRESENT __ If this flag is set, the Windows NT/Windows 2000 
messenger service is running on the remote client. 


| PORT_MULTILINKED If this flag is set, the port is multilinked with other 
- ports. You can use this information for displaying the 
connection status as a multilinked port. 


For a multilinked port, the RAS PORT STATISTICS 
structure contains two sets of statistics: one for the 
port alone, and another for the combined ports in the 
| 7 multilink connection. | 
~PPP_CLIENT If this flag is set, the remote client connected using 
| a | PPP. If this flag is not set, the remote client 
. 7 eee connected using the AMB protocol. 
REMOTE_LISTEN _ If this flag is set, the RemoteListen parameter of the 
ee ~ NetBIOS gateway is set to 1 on the server. 
USER_AUTHENTICATED _If this flag is set, a remote client is connected to the 
7 : server and the user has been authenticated. You can 
check this flag to ensure that a client is actually 
connected to a port. 
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If the MESSENGER_PRESENT, GATEWAY_ACTIVE, and REMOTE_LISTEN 

flags are set, you can use the Windows NT/Windows 2000 messenger service to 
send an administrative message to the remote client. If MESSENGER_PRESENT 
and REMOTE_LISTEN are set, but GATEWAY_ACTIVE is not, you can send a 
message to the client only if you send the message from the RAS server the client is 
dialed in to. 


wszUserName 
A null-terminated Unicode string that specifies the name of the remote user connected 
to this port. 


wszComputer 
A null-terminated Unicode string that specifies the name of the remote client 
computer. 


dwStartSessionTime 
Specifies the time, in seconds from January 1, 1970, that the client connected to the 
RAS server on this port. You can use the standard Win32 time routines to format this 
value for display. | 


wszLogonDomain 
A null-terminated Unicode string that specifies the name of the 
Windows NT/Windows 2000 domain on which the remote user was authenticated. 
This string is the domain name only, with no “\\” prefix. 


fAdvancedServer 
A flag that is nonzero if the RAS server associated with this port is a 
Windows NT/Windows 2000 Advanced Server. You can use this information to 
determine the name of the server that has the user account database. If the RAS 
server is an Advanced Server, you can get the name of the user account server by 
concatenating the prefix “\\” to the name returned in the wszLogonDomain member. 
This is because for an Advanced Server the local logon domain name is the same as 
the server name. If the RAS server is a Windows NT/Windows 2000 Workstation, you 
can use the RasAdminGetUserAccountServer function to get the name of the user 
account server. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RAS _PORT_1, RAS PORT _STATISTICS, RasAdminGetUserAccountServer, 
RasAdminPortEnum 
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RAS PORT_1 


The RAS_PORT_1 structure contains information about a RAS port. 


Members | | 


rasPort0 | 
A RAS_PORT_0 structure that contains information about the port, such as the name 
of the port, the name of the remote user connected to the port, and so on. 


LineCondition 
Specifies the state of the port. This member can be one of the following values. 


Value Meaning 


RAS _PORT_NON_OPERATIONAL _ The port is not operational. Check the event 
log for errors reported by the server. 


RAS_PORT_DISCONNECTED The port is currently disconnected. 
RAS_PORT_CALLING_BACK The RAS server is calling back the RAS 
Client. | 

RAS_PORT_LISTENING | The port is waiting for a client to call in. 

RAS_PORT_AUTHENTICATING The server is in the process of authenticatin 
| the remote client. 

RAS _PORT_AUTHENTICATED The remote client is now authenticated. 

RAS_PORT_INITIALIZING The device attached to the port is being 


initialized. The state of the port will change to 
RAS_PORT_LISTENING when the 
| 7 initialization has been completed. 


HardwareCondition 


Specifies one of the following values to indicate the state of the device attachedto 
the port. | ee ae 
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Value | | Meaning 

RAS_MODEM_OPERATIONAL - The modem attached to this port is 
operational and is ready to receive client 
calls. 


RAS_MODEM_HARDWARE_FAILURE ~— The modem attached to this port has a 
hardware problem. 


LineSpeed 
Specifies the speed, in bits per second, with which the computer can communicate 
with the port. 


NumStatistics 
This member is not used. The RAS administration functions, such as the 
RasAdminPortGetinfo function, use the RAS __ PORT_ STATISTICS structure to 
return port statistics. 


NumMediaParms 
Specifies the number of media-specific parameters for this port. For serial media this 
is typically the number of values that appear in the SERIAL.INI file. 
SizeMediaParms 
Specifies the size, in bytes, of the buffer required for all media-specific pain oe 
The RasAdminPortGetinfo function returns a buffer containing an array of 
RAS_PARAMETERS structures with the media parameters and values for the port. 
ProjResult 
A RAS_PPP_PROJECTION_RESULT structure that specifies the PPP projection 
information for this port. This structure provides information for each protocol that is 
negotiated when a RAS client connects to a server. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Sinictliee: 
RAS PARAMETERS, RAS_PORT_0, RAS_PORT_STATISTICS, 
RAS_PPP_PROJECTION_RESULT, RasAdminAcceptNewConnection, 
RasAdminConnectionHangupNotification, RasAdminPortGetinfo 


RAS PORT STATISTICS 


The RAS_PORT_STATISTICS structure reports the statistics that a RAS server collects 
for a connected port. The RAS server resets the various statistic counters each time the 
port is connected. You can call the RasAdminPortClearStatistics function to force the 

RAS server to reset the statistic counters. 
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Members 


dwBytesXmited 
Specifies the total number of bytes transmitted by the connection. 


dwBytesRcved 
Specifies the total number of bytes received by the connection. 


dwFramesXmited 
Specifies the total number of frames transmitted by the connection. 


dwFramesRcved | : 
Specifies the total number of frames received by the connection. 


dwCrcErr 
Specifies the total number of CRC errors on the connection. CRC errors are caused 
by the failure of a cyclic redundancy check. A CRC error indicates that one or more 
characters in the data packet received were found garbled on arrival. 


dwTimeoutErr 
Specifies the total number of time-out errors on the connection. Time-out errors occur 
when an expected character is not received in time. When this occurs, the software 
assumes that the data has been lost and requests that it be resent. 


dwAlignmentErr 
Specifies the total number of alignment errors on the connection. Alignment errors 
occur when a character received is not the one expected. This usually happens when 
~acharacter is lost or when a time-out error occurs. 


dwHardwareOverrunErr 
Specifies the total number of hardware overrun errors on the connection. These errors 
indicate the number of times the sending computer has transmitted characters faster 
than the receiving computer hardware can process them. If this problem persists, 
reduce the BPS connection rate on the client. 


dwFramingErr 
Specifies the total number of framing errors on the connection. A framing error occurs 
when an asynchronous character is received with an invalid start or stop bit. 


dwBufferOverrunErr 
Specifies the total number of buffer overrun errors on the connection. A buffer overrun 
error occurs when the sending computer is transmitting characters faster than the 
receiving computer can accommodate them. If this problem persists, reduce the BPS 
connection rate on the client. 


dwBytesXmitedUncompressed | 
Specifies the total number of bytes transmitted uncompressed by the connection. 


_ dwBytesRcvedUncompressed 


Specifies the total number of bytes received uncompressed by the connection. 


dwBytesXmitedCompressed 
Specifies the total number of bytes transmitted compressed by the connection. 


dwBytesRcvedCompressed 
Specifies the total number of bytes received compressed by the connection. 


Chapter 10 RAS Server Administration Reference 301 


dwPortBytesXmited 
Specifies the total number of bytes transmitted by the port. 


dwPortBytesRcved 
Specifies the total number of bytes received by the port. 


dwPortFramesXmited 
Specifies the total number of frames transmitted by the port. 


dwPortFramesRcved 
Specifies the total number of frames received by the port. 


dwPortCrcErr 
Specifies the total number of CRC errors on the port. CRC errors are caused by the 
failure of a cyclic redundancy check. A CRC error indicates that one or more 
characters in the data packet received were found garbled on arrival. 


dwPortTimeoutErr 
Specifies the total number of time-out errors on the port. Time-out errors occur when 
an expected character is not received in time. When this occurs, the software 
assumes that the data has been lost and requests that it be resent. 


dwPortAlignmentErr 
Specifies the total number of alignment errors on the port. Alignment errors occur 
when a character received is not the one expected. This usually happens when a 
character is lost or when a time-out error occurs. 


dwPortHardwareOverrunErr 

Specifies the total number of hardware overrun errors on the port. These errors 
indicate the number of times the sending computer has transmitted characters faster 
than the receiving computer hardware can process them. If this problem persists, 
reduce the BPS connection rate on the client. 


dwPortFramingErr 
Specifies the total number of framing errors on the port. A framing error occurs when 
an asynchronous character is received with an invalid start or stop bit. 


dwPortBufferOverrunErr 
Specifies the total number of buffer overrun errors on the port. A buffer overrun error. 
occurs when the sending computer is transmitting characters faster than the receiving 
computer can accommodate them. If this problem persists, reduce the BPS 
~ connection rate on the client. 


dwPortBytesXmitedUncompressed 
Specifies the total number of bytes transmitted lincammprsecoe by the port. If the Soi 
is part of a multilink connection, this member is not valid. Use the compression 
statistics for the connection instead. 


dwPortBytesRcvedUncompressed 
Specifies the total number of bytes received uncompressed by the en if the port is 
part of a multilink connection, this member is not valid. Use the compression Statistics 
for the connection instead. 
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dwPortBytesXmitedCompressed 
Specifies the total number of bytes transmitted compressed by the port. If the port is 
~ part of a multilink connection, this member is not valid. Use the compigeson statistics 
for the connection instead. 


dwPortBytesRcvedCompressed 
Specifies the total number of bytes received compressed by the port. If the port is part 
of a multilink connection, this member is not valid. Use the compression Statistics for 
the connection instead. | 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RAS_PORT_0, RasAdminAcceptNewConnection, 
RasAdminConnectionHangupNotification, RasAdminPortClearStatistics, 
RasAdminPortGetinfo 


RAS_PPP_ATCP_RESULT 


The RAS_PPP_ATCP_RESULT structure is used to report the result of an AppleTalk 
protocol projection epee on for a port. Windows NT version 4.0 does not use this 
structure. . 


Members 


dwError 7 
Specifies a value that indicates the results of the AppleTalk projection operation. A » 
value of NO_ERROR indicates success, in which case, the wszAddress member is 
valid. If the projection operation is not successful, OWwEMOn isan error code from 
Winerror.h or Raserror.h. 


wszAddress 
Specifies a null-terminated Unicode string that specifies the IP address Besigned to 
the remote client. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. | 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RAS_ PPP_ PROJECTION_RESULT 


RAS PPP IPCP RESU LT 


The RAS_PPP_IPCP_RESULT structure is used to report the result of a PPP Internet 
Protocol (IP) projection operation for a port. 


Members 
dwError 
Indicates the results of the IP projection operation. A value of NO_ ERROR indicates 
success, in which case, the wszAddress member is valid. If the projection operation | 
was not successful, dwError is an error code from Winerror.h or Raserror.h. | 


| wszAddress 


A null-terminated Unicode string that specifies the IP address assigned to the remote 
client. This string has the “a.b.c.a" form. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


_ Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RAS_PORT_1, RAS_PPP_PROJECTION RESULT, RasAdminPortGetinfo | 


RAS_ PPP_ IPXCP_ RESULT 


The RAS _ PPP_ IPXCP__ RESULT structure is used to radon the result of a PPP 
Internetwork Packet Exchange (IPX) projection operation for a port. 
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Members 


dwError 
Indicates the results of the IPX projection operation. A value of NO_ERROR indicates 


success, in which case, the wszAddress member is valid. If the projection operation 
was not successful, dwError is an error code from Winerror.h or Raserror.h. — 


wszAddress 
A null-terminated Unicode string that specifies the IPX address assigned to the 


remote client. This string has the “net.node” form. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetinfo 


RAS_PPP_NBFCP_RESULT 


The RAS_PPP_NBFCP_RESULLT structure is used to report the result of a PPP 
NetBEUI Framer (NBF) projection operation for a port. 


Members 


dwError 
Indicates the results of the NBF projection operation. A value of NO_ERROR 
indicates success, in which case, the wszWksta member contains the name of the 


remote computer. If the projection operation was not successful, dwError is an error 
code from Winerror.h or Raserror.h. 


dwNetBiosError | 
_ Ignore this member on the server; it is relevant only on the client. 
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szName 
Ignore this member on the server; it is relevant only on the client. 


wszWksta 
A null-terminated Unicode string that specifies the NetBIOS name of the RAS client , 
workstation. : 


‘Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RAS_PORT_1, RAS_PPP_PROJECTION_RESULT, RasAdminPortGetinfo 


RAS_PPP_PROJECTION_RESULT 


The RAS_PPP_PROJECTION_RESULT structure is used to report the results of the 
various PPP projection operations for a port. 


Members 


nbf | 
A RAS_PPP_NBFCP_RESULT structure that reports the result of a PPP NetBEUI 
Framer (NBF) projection operation. 


A RAS_PPP_IPCP_RESULLT structure that reports the result of a PPP Internet 
Protocol (IP) projection operation. 


ipXx 
A RAS_PPP_IPXCP_RESULT structure that reports the result of a PPP Internetwork 
Packet Exchange (IPX) projection operation. 


a 
A RAS_PPP_ATCP_RESULT structure. Windows NT version 4.0 does not use this 
member. 


306 Volume 4 Remote Access Services 


Remarks | 

This structure reports the projection results for NetBEUI, TCP/IP, and IPX protocols. 
Each PPP structure has a dwError member that indicates whether the other information 
in the structure is valid. lf dwError is NO_ERROR, the other information is valid. If 
dweError is one of the error codes in Winerror.h or Raserror.h, the other information is 


not valid. 


Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RAS PORT_1, RAS_PPP_ATCP_RESULT, RAS_PPP_IPCP_RESULT, 
RAS_PPP_IPXCP_RESULT, RAS_PPP_NBFCP_RESULT, RasAdminPortGetinfo 


RAS_SECURITY_INFO © 


The RAS_SECURITY_INFO structure is used with the RasSecurityDialogGetInfo 
function to return information about the RAS port associated with a RAS security DLL 


authentication transaction. 


mre 


Members 

LastError — _ | | 
Specifies an error code that indicates the state of the last RasSecurityDialogReceive 
call for the port. If the receive operation failed, LastError is one of the error codes 
defined in Raserror.h or Winerror.h. Otherwise, LastError is one of the following 


values. 
Value Meaning | 
SUCCESS | The receive operation has been successfully completed. The 


BytesReceived member indicates the number of bytes received. 
PENDING The receive operation is pending completion. 
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BytesReceived 
Specifies the number of bytes received in the most recent 


RasSecurityDialogReceive operation. This member is valid only if the value of the 
LastError member is SUCCESS. 


DeviceName 
Specifies a null-terminated string that contains the user-friendly display name of the 
device on the port, such as Hayes SmartModem 9600. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Rasshost.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RasSecurityDialogGetinfo, RasSecurityDialogReceive 


RAS_SERVER_0 os 


The RAS_SERVER_0 structure is used by the RasAdminServerGetinfo function to 
return information about the ports configured on a RAS Server. 


Members 


TotalPorts 
Specifies the total number of ports configured on the RAS server that are available for 
remote clients to connect to. For example, if the total number of ports configured for 
dialing in to a server is four, but one of the ports is currently in use for dialing out, 
TotalPorts will be three. | 


PortsinUse 
Specifies the number of ports currently in use by remote clients. 


RasVersion 
Specifies the version of the RAS server. You can use this information to take version- 
specific action. This member can be one of the following values. 
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Description 


Value 


RASDOWNLEVEL 


RASA 


Indicates a LAN Manager version 1.0 RAS server. 
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dwBytesXmited 
The number of bytes transmitted through this connection or link. 


dwBytesRcved 
The number of bytes received through this connection or link. 


dwFramesXmited | 
The number frames transmitted through this connection or link. 


dwFramesRcved 
The number of frames received through this connection or link. 


dwCrcErr | | 
The number of Cyclic Redundancy Check (CRC) errors on this connection or link. 


dwTimeoutErr 

The number of timeout errors on this connection or link. 
dwAlignmentErr 

The number of alignment errors on this connection or link. 


dwHardwareOverrunErr 
The number of hardware overrun errors on this connection or link. 


dwFramingErr 
The number of framing errors on this connection or link. 


dwBufferOverrunErr 
The number of buffer overrun errors on this connection or link. 


dwCompressionRatioIn © 
The compression ratio for the data being received on this connection or link. 


dwCompressionRatioOut 
The compression ratio for the data being transmitted on this connection or link. 


dwBps 
The speed of the connection or link, in bits per second. 


For a single-link connection and for individual links in a multilink connection, this 
speed is negotiated at the time the connection or link is established. 


For multilink connections, this speed is equal to the sum of the speeds of the 
individual links. For multilink connections, this epeen will vary as links are added or 
deleted. 


This speed is not equal to the throughput of the connection or link. To calculate the 
average throughput, divide the number of bytes transmitted (dwBytesXmited) and 
received (dwBytesRcved) by the amount of time the connection or link has been up 
(dwConnectDuration). 


dwConnectDuration 
The amount of time, in seconds, that the connection or link has been connected. 
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Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ras.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RasClearConnectionStatistics, RasClearLinkStatistics, 
RasGetConnectionStatistics, RasGetLinkStatistics 


RAS USER _0 


The RAS_USER_0 structure is used in the RasAdminUserSetinfo and 
RasAdminUserGetinfo functions to specify information about a user. 


Members 

bfPrivilege re 7 | 
A set of bit flags that specify the RAS privileges of the user. This member can be a 
combination of the RASPRIV_DialinPrivilege flag and one of the call-back flags. Note 
that when you call the RasAdminUserSetinfo function, you must specify one of the 


call-back flags. You can use the RASPRIV_CallbackType mask to identify the type of 
call-back privilege provided to the user. The following flags are defined. 


Value — : Meaning 
RASPRIV_NoCallback | . The user has no call-back privilege. 
RASPRIV_AdminSetCallback The user account is configured to have the 
administrator set the call-back number. 
: RASPRIV_CallerSetCallback The remote user can specify a call-back phone 
a | ie number when dialing in. 
-RASPRIV_DialinPrivilege The user has permission to dial in to this server. 
szPhoneNumber 


A null-terminated Unicode string that specifies the call-back phone number for 
the user. 
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Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h.. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RasAdminUserGetinfo, RasAdminUserSetinfo 


SECURITY MESSAGE 


The SECURITY_MESSAGE structure is used with the RasSecurityDialogComplete 
function to indicate the results of a RAS security DLL authentication transaction. 


Members 

dwMsgld | noe | 

__ Indicates whether the RAS server should grant access to the remote user. This 
member can be one of the following values. ey : 


Value | Meaning 


SECURITYMSG_SUCCESS The security DLL successfully authenticated the 
| remote user identified by the UserName member. 
The RAS server will proceed with its PPP 
authentication. sees 


SECURITYMSG_FAILURE The security DLL denied access to the remote 
user identified by the UserName member. The 
_ RAS server will hang up the call and record the 
failed authentication in the Windows NT/2000 © 
~ eventlog. < 
SECURITYMSG_ERROR __ Aneerror occurred that prevented validation of the 
remote user. The RAS server will hang up the call 
and record the error in the Windows NT/2000 
eventlog. — 
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hPort 
_ Specifies the port handle that the RAS server passed to the security DLL in the 

RasSecurityDialogBegin call for this authentication transaction. 

dwError 
Specifies an error code. If dwMsglid is SECURITYMSG_ERROR, set dwError to one 
of the nonzero error codes defined in Winerror.h or Raserror.h. The RAS server 
records this error code in the Windows NT/Windows 2000 event log. lf the dwMsgld 
member indicates success or failure, set dwError to zero. 

UserName | 
Specifies the name of the remote user if dwMsgld is SECURITYMSG_SUCCESS or 
SECURITYMSG_FAILURE. This string can be empty if dwMsgld is 
SECURITYMSG_ERROR. 

Domain 
Specifies the name of the logon domain for the remote user if dwMsgld is 
SECURITYMSG_SUCCESS or SECURITYMSG_FAILURE. This string can be empty 
if dwMsgld is SECURITYMSG_ERROR. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Windows 95/98: Unsupported. 
Header: Declared in Rasshost.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Structures, 
RasSecurityDialogBegin, RasSecurityDialogComplete 


RAS Server Administration Union 


For Windows NT version 4.0, use the following union to implement RAS Server 
Administration functionality. Windows 95 does not provide RAS server support. 


RAS PARAMS VALUE 


RAS_PARAMS_ VALUE 


The RAS_PARAMS_VALUE union is used in the RAS_ PARAMETERS structure to. 
store the data associated with a media-specific parameter. The P_Type member of the 
RAS_PARAMETERS structure uses a value from the RAS_PARAMS_FORMAT 
enumeration to indicate the type of value currently stored in RAS_PARAMS_VALUE. 
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Members 


Number : 
lf the P_Type member of the RAS_PARAMETERS structure is ParamNumber, the 
Number member contains the value of the media-specific parameter. For example, 
the MAXCONNECTEBPS parameter is of type ParamNumber, and the value might be 
19200. | | | 
lf the P_Type member of the RAS_PARAMETERS structure is ParamNumber, the 
Number member contains the value of the media-specific parameter. For example, 
the MAXCONNECTBPS parameter is of type ParamNumber, and the value might be 
19200. 
String | 
If the P_Type member of the RAS_PARAMETERS structure is ParamString, the | 
String member contains the value of the media-specific parameter. 
Length | 
Specifies the length, in characters, of the string pointed to by the Data member. 
Data 
Pointer to a buffer that contains the string value of a media-specific parameter. 


Windows NT/2000: Requires Windows NT 4.0 or later. 


Header: Declared in Rassapi.h. 


Remote Access Service (RAS) Overview, RAS Server Administration Union, 
RAS_PARAMETERS, RAS_PARAMS_FORMAT 


RAS Server Administration Enumeration Types 


For Windows NT version 4.0, use the following enumeration to implement RAS Server 
Administration functionality. Windows 95 does not provide RAS server support. 


RAS_PARAMS_FORMAT 
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Indicates that the data associated with the key is a string. 


ParamString 


= 


Rethononcncs 


Requires Windows NT 4.0 or later. 


Declared in Rassapi.h. 


Windows NT/2000 


Header 
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(continued) | 7 


Every router manager installed in the system will have a registry key created under the 
Router key. The DLLPath variable specifies the location of the DLL corresponding to the 
router manager and the ProtocollD variable specifies the protocol family identifier for the 
router manager. | | | 


The Interfaces key is populated with the interfaces that have been added to the local 
system from the Router configuration. Each interface has an associated Type (Internal, 
Dedicated, or Dynamic) and subkeys for each router manager (IP and IPX for example). 


About Remote Access Service Administration 


Microsoft® Windows® 2000 provides a set of functions for administering user 
ermissions and ports on Windows 2000 RAS servers. Using these functions, you can 
| develop a RAS server administration application to perform the following tasks: 


e Enumerate those users who have a specified set of RAS permissions 

e Assign or revoke RAS permissions for a specified user 

e Enumerate the configured ports on a RAS server 7 
e Get information and statistics about a specified port on a RAS server 

e Reset the statistics counters for a specified port 

e Disconnect a specified port . | 


You can also install a RAS server administration DLL for auditing user connections and 
assigning IP addresses to dial-in users. The DLL exports a set of functions that the RAS 
server calls whenever a user tries to connect or disconnect. 


User Administration 


A Windows® 2000 RAS server uses a user account database that contains information 
about a set of user accounts. The information includes a user’s RAS privileges, which 

| are a set of bit flags that determine how the RAS server responds when the user calls to 
connect. You can use the RAS server administration functions to locate the user account 
database, and to get and set the RAS privileges for user accounts. 
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A Windows 2000 RAS server can be part of a Windows 2000 domain, or it can be a 
stand-alone Windows 2000 Server or Windows 2000 Professional workstation that is not 
part of a domain. For a server that is part of a domain, the user account database is 
stored on the Windows NT/Windows 2000 server that is the Primary Domain Controller 
(PDC). A stand-alone server stores its own local user account database. To get the 
name of the server that stores the user account database used by a specified RAS 
server, you can call the MprAdminGetPDCServer function. You can then use the name 
of the user account server in a call to the NetQueryDisplaylinformation function to 
enumerate the users in a user account database. You can also use the server name in 
calls to the MprAdminUserGetinfo and MprAdminUserSetinfo functions to get and set 
the RAS privileges for a specified user account. 


The MprAdminuUserGetInfo and MprAdminUserSetinfo functions use the 
RAS_USER_0 structure to specify a user’s RAS privileges and call-back phone number. 
The RAS privileges indicate the following information: 


e Whether the user can make a remote connection to the server or the domain to which 
the server belongs. 


© Whether the user can establish a connection through a call back, in which the RAS 
server hangs up and then calls back to the user to establish the connection. 


Each user account specifies one of the following flags to indicate the user’s call-back 


privileges. 
Value Meaning 
RASPRIV_NoCallback - The RAS server will not call back the user to establish a 
ope: connection. 


RASPRIV_AdminSetCallback When the user calls, the RAS server hangs up and calls a preset 


call-back phone number stored in the user account database. 
The szPhoneNumber member of the RAS_USER_0 structure 
contains the user’s call-back phone number. 


_ RASPRIV_CallerSetCallback When the user calls, the RAS server provides the option of 


specifying a phone number to call back. The user can also 

~ choose to connect immediately without a call back. The _ 
szPhoneNumber member contains a default number that the 
user can override. 7 


RAS Server snd Port Administration | 


You can use the RAS server administration functions to get information about a specified 
_ RAS server and its ports. These functions can also be used to terminate a connection on 


__aspecified RAS server port. | 
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The MprAdminServerGetinfo function returns a MPR_SERVER_0 structure that 
contains information about the configuration of a RAS server. The returned information 
includes the number of ports currently available for connection, the number of ports 
currently in use, and the server version number. 


The MprAdminPortEnum function retrieves an array of RAS_PORT_0 structures that | 
contains information for each of the ports configured on a RAS server. oie information 
for each port includes: 


e The name of the port 
e Information about the device attached to the port 


e Whether the RAS server associated with the portis a Windows NT/Windows 2000 
Server 


e Whether the port is currently in use, and, f it is, information about the connection 


You can call the MprAdminPortGetinfo function to get additional information about a 
specified port on a RAS server. This function returns a RAS_PORT_1 structure that 
contains a RAS_PORT_0 structure and additional information about the current state of 
the port. The RasAdminPortGetinfo function also returns an array of 
RAS_PARAMETERS structures that describe the values of any media-specific keys 
associated with the port. A RAS_- PARAMETERS structure uses a value from the 
RAS_PARAMS_FORMAT enumeration to indicate the format of the value for ao 
media-specific key. 


The MprAdminPortGetinfo function also returns a RAS_PORT_STATISTICS structure 
that contains various statistic counters for the current connection, if any, on the port. For 
a port that is part of a multilink connection, MprAdminPortGetinfo returns statistics for 
the individual port and cumulative statistics for all ports involved in the connection. You 
can use the MprAdminPortClearStats function to reset the statistic counters for the 
port. The MprAdminPortDisconnect function disconnects a port that is in use. 


Use the MprAdminBufferFree function to free memory allocated by the 
MprAdminPortEnum and MprAdminPortGetinfo functions. Use the 
MprAdminGetErrorString function to get a string that describes a RAS error code 
returned by one of the RAS server administration (RasAdmin) functions. 


RAS Administration DLL 


Microsoft® Windows NT® version 4.0 makes it possible for you to install a RAS 
administration DLL on a Windows NT version 4.0 RAS server. The DLL exports functions 
that the RAS server calls whenever a user tries to connect or disconnect. You can use 
the DLL to perform the following administrative functions: | 


© Decide whether to allow a user to connect to the server. This can provide a security 
check in addition to the standard RAS user authentication. 


e Record the time that each user connects to and disconnects from the server. This can 
be useful for billing or auditing purposes. 
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e Assign an IP address to each user. This can be useful for security, since you can use 
this feature to map a user’s connection to a specific computer. 


Implement the following functions when developing a RAS server administration DLL: 


e MprAdminAcceptNewConnection 
MprAdminConnectionHangupNotification 
¢ MprAdminGetlpAddressForUser 

e MprAdminReleaselpAddress 


A RAS administration DLL must implement and export all of the above functions. If any 
of the functions are not implemented, the remote access service will not start. 


The MprAdminAcceptNewConnection and 
MprAdminConnectionHangupNotification functions enable the DLL to audit user 
connections to the server. A Windows NT/Windows 2000 RAS server calls the 
MprAdminAcceptNewConnection function whenever a user tries to connect. This 
function can prevent the user from connecting. You can also use the 
MprAdminAcceptNewConnection function to generate an entry in a log for billing or 
auditing. When the user disconnects, the RAS server calls the 
MprAdminConnectionHangupNotification function, which can log the time at which 
the user disconnected. 


After the RAS server has authenticated a caller, it calls the 
MprAdminGetipAddressForUser function to get an IP address for the remote client. 
‘The DLL can use this function to provide an alternate scheme to map an IP address to a 
dial-in user. If MprAdminGetlpAddressForUser is not implemented, a RAS server 
connects a remote user to an IP address that is selected from a static pool of IP 
addresses, or one selected by a Dynamic Host Configuration Protocol (DHCP) server. 
The MprAdminGetlpAddressForUser function allows the DLL to override this default IP 
address and specify a particular IP address for each user. The | 
MprAdminGetlpAddressForUser function can set a flag that causes RAS to call the 
MprAdminReleaselPAddress function when the user disconnects. The DLL can use 
MprAdminReleaselPAddress to update its user-to-IP-address map. © 


RAS serializes calls into the administration DLL. A call into one of the DLL’s functions for 
a given RAS client will not be preempted by a call to that function for a different RAS 
client; RAS will not call the function for the other client until the initial call is complete. 
Furthermore, serialization extends to certain groups of functions. The IP address 
functions are serialized as a group; a call into either MprAdminGetlpAddressForUser 
or MprAdminReleaselpAddress blocks calls into both functions until the initial call is 


- complete. MprAdminAcceptNewConnection and 


MprAdminConnectionHangupNotification | are also serialized as a 4 group. 
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RAS executes the functions for assigning IP addresses in one process; the functions for 
connection and disconnection notifications are executed in another process. 


- Consequently, the DLL should not depend on shared data between these two sets of 


functions. 


The RAS server logs an error in the system event log if an error occurs when it tries to 
load a RAS administration DLL or when calling one of the DLL’s functions. This can 
happen, for example, if the DLL specified the wrong name for an exported function, or if 
it did not include the function name in the DEF file. The entry in the event log indicates 
the reason for the failure. 


Windows 2000 and later: RAS administration DLLs that implement this function 
interface do not work on Windows 2000 and later versions. For Windows 2000 and later 
versions, use the MprAdmin function interface provided with the more recent versions of 
Windows. For more information, see the RAS Administration Reference in the Routing 
and RAS documentation. 


RAS Administration DLL Registry Setup 


The setup program for a third-party RAS administration DLL must register the DLL with 
RAS by providing information under the following key in the registry: 


HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIl 


To register the DLL, set the following values under this key. 


Value name Value data 

DisplayName A REG_SZ string that contains the user-friendly display name of 
the DLL. 

DLLPath | A REG_SZ string that contains the full path of the DLL. 


For example, the registry entry fora RAS SGministAanon DLL from a fictional company 
named Netwerks Corporation might be: : 
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIil 
DisplayName : REG_SZ : Netwerks RAS Admin DLL 
DLLPath : REG_SZ : C:\nt\system32\ntwkadm.dll 


The setup program for a RAS administration DLL should also provide remove/uninstall — 
functionality. If a user removes the DLL, the setup program should delete the registry 


entries for the DLL. 
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Remote Access Service 
Administration 


Remote Access Services Administration Overview 


Microsoft® Windows® 2000 provides a set of functions for administering user 
permissions and ports on Windows 2000 RAS servers. Using these functions, you 
can develop a RAS server administration application to perform the following tasks: 


e Enumerate those users who have a specified set of RAS permissions 
e Assign or revoke RAS permissions for a specified user 

e Enumerate the configured ports on a RAS server 

e Get information and statistics about a specified port on a RAS server 
e Reset the statistics counters for a specified port 

e Disconnect a specified port | 


You can also install a RAS server administration DLL for auditing user connections and 
assigning IP addresses to dial-in users. The DLL exports a set of functions that the RAS 
server calls whenever a user tries to connect or disconnect. 


RAS User Administration 


A Windows® 2000 RAS server uses a user account database that contains information 
about a set of user accounts. The information includes a user’s RAS privileges, which 
are a set of bit flags that determine how the RAS server responds when the user calls to 
connect. You can use the RAS server administration functions to locate the user account 
database, and to get and set the RAS privileges for user accounts. 


A Windows 2000 RAS server can be part of a Windows 2000 domain, or it can be a 
stand-alone Windows 2000 Server or Windows 2000 Professional workstation that is not 
part of a domain. For a server that is part of a domain, the user account database is 
stored on the Windows NT/Windows 2000 server that is the Primary Domain Controller 
(PDC). A stand-alone server stores its own local user account database. To get the 
name of the server that stores the user account database used by a specified RAS 
server, you can call the MprAdminGetPDCServer function. You can then use the name 
of the user account server in a call to the NetQueryDisplaylinformation function to 
enumerate the users in a user account database. You can also use the server name in 
calls to the MprAdminUserGetinfo and MprAdminUserSetinfo functions to get and set 
the RAS privileges for a specified user account. 
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The MprAdminUserGetInfo and MprAdminUserSetinfo functions use the : 
RAS_USER_0 structure to specify a user’s RAS privileges and call-back phone number. 
The RAS privileges indicate the following information: 


e Whether the user can make a remote connection to the server or the domain to which 
the server belongs. 


e Whether the user can establish a connection through a call back, in which the RAS 
server hangs up and then calls back to the user to establish the connection. 


_ Each user account specifies one of the following flags to indicate the user’s call-back 


privileges. 
Value Meaning 
RASPRIV_NoCallback The RAS server will not call back the user to 


establish a connection. 


RASPRIV_AdminSetCallback -When the user calls, the RAS server hangs up and 
calls a preset call-back phone number stored in the 
user account database. The szPhoneNumber 
member of the RAS_USER_0 structure contains the 
user’s call-back phone number. 


RASPRIV_CallerSetCallback When the user calls, the RAS server provides the 
option of specifying a phone number to call back. 
The user can also choose to connect immediately 
- without a call back. The szPhoneNumber member 
contains a default number that the user can 
override. : 


RAS Server and Port Administration 


You can use the RAS server administration functions to get information about a specified 
RAS server and its ports. These functions can also be used to terminate a connection on 
a specified RAS server port. 


The MprAdminServerGetinfo function returns a MPR_SERVER_0 structure that 
contains information about the configuration of a RAS server. The returned information 
includes the number of ports currently available for connection, the number of ports 
currently in use, and the server version number. 


The MprAdminPortEnum function retrieves an array of RAS_PORT_0 structures that 
contains information for each of the ports configured on a RAS server. The information 
for each port includes: 

e The name of the port 


e Information about the device attached to the port 
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e Whether the RAS server associated with the port is a Windows NT/Windows 2000 
Server 


e Whether the port is currently in use, and, if it is, information about the connection 


You can call the MprAdminPortGetiInfo function to get additional information about a 
specified port on a RAS server. This function returns a RAS_PORT_1 structure that 
contains a RAS_PORT_0 structure and additional information about the current state of 
the port. The RasAdminPortGetinfo function also returns an array of 
RAS_PARAMETERS structures that describe the values of any media-specific keys 
associated with the port. A RAS_- PARAMETERS structure uses a value from the 

RAS _PARAMS_FORMAT enumeration to indicate the format of the value for each 
media-specific key. 


The MprAdminPortGetinfo function also returns a RAS_PORT_STATISTICS structure 
that contains various statistic counters for the current connection, if any, on the port. For 
a port that is part of a multilink connection, MprAdminPortGetinfo returns statistics for 
the individual port and cumulative statistics for all ports involved in the connection. You 
can use the MprAdminPortClearStats function to reset the statistic counters for the 
port. The MprAdminPortDisconnect function disconnects a port that is in use. 


Use the MprAdminBufferFree function to free memory allocated by the 
MprAdminPortEnum and MprAdminPortGetinfo functions. Use the 
MprAdminGetErrorString function to get a string that describes a RAS error code 
returned by one of the RAS server administration (RasAdmin) functions. 


RAS Administration DLL 


Microsoft® Windows NT® version 4. 0 makes it possible for you to install a RAS 
administration DLL on a Windows NT version 4.0 RAS server. The DLL exports functions 
that the RAS server calls whenever a user tries to connect or disconnect. You can use 
the DLL to perform the following administrative functions: 


© Decide whether to allow a user to connect to the server. This can provide a security 
check in addition to the standard RAS user authentication. 


e Record the time that each user connects to and disconnects from the server. This can 
be useful for billing or auditing purposes. 


e Assign an IP address to each user. This can be useful for security, since you can use 
this feature to map a user’s connection to a specific computer. 


Implement the following functions when developing a RAS server administration DLL: _ 
¢ MprAdminAcceptNewConnection 
~@ MprAdminConnectionHangupNotification 


e MprAdminGetipAddressForUser 
e MprAdminReleaselpAddress 
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A RAS administration DLL must implement and export all of the above functions. If ay 
of the functions are not implemented, the remote access service will not start. 


_ The MprAdminAcceptNewConnection and 


MprAdminConnectionHangupNotification functions enable the DLL to audit user 
connections to the server. A Windows NT/Windows 2000 RAS server calls the 
MprAdminAcceptNewConnection function whenever a user tries to connect. This 
function can prevent the user from connecting. You can also use the 
MprAdminAcceptNewConnection function to generate an entry in a log for billing or 
auditing. When the user disconnects, the RAS server calls the 
MprAdminConnectionHangupNotification function, which can log the time at which 
the user disconnected. 


After the RAS server has authenticated a caller, it calls the 
MprAdminGetipAddressForUser function to get an IP address for the remote client. 
The DLL can use this function to provide an alternate scheme to map an IP address to a 
dial-in user. If MprAdminGetlpAddressForUser is not implemented, a RAS server 
connects a remote user to an IP address that is selected from a static pool of IP 
addresses, or one selected by a Dynamic Host Configuration Protocol (DHCP) server. 


_ The MprAdminGetlpAddressForUser function allows the DLL to override this default IP 


address and specify a particular IP address for each user. The 
MprAdminGetlpAddressForUser function can set a flag that causes RAS to call the 
MprAdminReleaselPAddress function when the user disconnects. The DLL can use 
MprAdminReleaselPAddress to update its user-to-IP-address map. 


RAS serializes calls into the administration DLL. A call into one of the DLL’s functions for 
a given RAS client will not be preempted by a call to that function for a different RAS 
client; RAS will not call the function for the other client until the initial call is complete. 
Furthermore, serialization extends to certain groups of functions. The IP address 
functions are serialized as a group; a call into either MprAdminGetlpAddressForUser 
or MprAdminReleaselpAddress blocks calls into both functions until the initial call is 
complete. MprAdminAcceptNewConnection and 
MprAdminConnectionHangupNotification are also serialized as a group. 


RAS executes the functions for assigning IP addresses in one process; the functions for 
connection and disconnection notifications are executed in another process. 
Consequently, the DLL should not ae on shared data between these two sets Or. 
functions. 7 


The RAS server logs an error in the system event log if an error occurs when it tries to 
load a RAS administration DLL or when calling one of the DLL’s functions. This can 
happen, for example, if the DLL specified the wrong name for an exported function, or if 
it did not include the function name in the DEF file. The entry in the event log indicates 
the reason for the failure. 
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Windows 2000 and later: RAS administration DLLs that implement this function 
interface do not work on Windows 2000 and later versions. For Windows 2000 and later 
versions, use the MprAdmin function interface provided with the more recent versions of 
Windows. For more information, see the RAS Administration Reference in the Routing _ 
and RAS documentation. | 


RAS Administration DLL Registry Setup 


The setup program for a third-party RAS administration DLL must register the DLL with 
RAS by providing information under the following key in the registry: 


HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RAS\AdminDIl 


To register the DLL, set the following values under this key. 


Valuename Value data 

DisplayName A REG_SZ string that contains the user- friendly copay name of 
; ~~» the DLL. 

DLLPath _ AREG_SZ string that contains the full path of the DLL. 


For Senile the registry entry fora RAS administration DLL from a fictional company | 
-named Netwerks Corporation might be: | 


HKEY_LOCAL_ MACHINE\SOFTWARE\Microsoft\RAS\AdminDIl 
DisplayName : REG SZ. Netwerks RAS Admin DLL 
-DLLPath : REG SZ: C:\nt\system32\ntwkadm.dil 


The setup program for a RAS administration DLL should also provide remove/uninstall 
functionality. If a user removes the DLL, the setup program should delete the registry 
entries for the DLL. 


Remote Access Service Administration Reference 


This chapter describes the reference elements used to implement the Remote Access 
Service (RAS) for Microsoft® Windows NT® version 4.0. 


The RAS API is distributed as a feature of Microsoft Windows 2000. RAS can also be 
downloaded and used as a component of either Windows 2000 or Windows NT 4.0. 
RAS in either of these forms provides the same functionality. The only difference is the 
naming convention that! is used for the reference elements in each version of the 

RAS API. 


The functions that are used to implement RAS for Windows NT 4.0 V'typicaliy begin with 
_ the “RasAdmin” prefix. The analogous functions for RRAS begin with the “MprAdmin” 
Prerx: 
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For example, Windows NT 4.0 RAS provides a function called RasAdminPortGetinfo. 
The analogous function in RRAS is called MprAdminPortGetinfo. Another example: 
Windows NT 4.0 RAS provides the callback function RasAdminGetlpAddressForUser. 
RRAS provides a similar callback function called MprAdminGetipAddressForUser. 
Exceptions to this rule are RasAdminPortClearStatistics, which, under RRAS is 
MprAdminPortClearStats, and RasAdminFreeBuffer, which under RRAS is 


MprAdminBufferFree. 


The following table lists the Windows NT 4.0 RAS functions and the corresponding 


RRAS functions. 
Windows NT 4.0 RAS 


RasAdminAcceptNewConnection 
RasAdminConnectionHangupNotification 
RasAdminFreeBuffer 
RasAdminGetErrorString 
RasAdminGetipAddressForUser 
RasAdminPortClearStatistics 
RasAdminPortDisconnect 
RasAdminPortEnum 
RasAdminPortGetinfo 
RasAdminReleaselpAddress | 
RasAdminUserGetinfo 
RasAdminUserSetinfo 


RRAS 


7 MprAdminAcceptNewConnection 


MprAdminConnectionHangupNotification 
MprAdminBufferFree 
MprAdminGetErrorString 
MprAdminGetlpAddressForUser 
MprAdminPortClearStats 
MprAdminPortDisconnect 
MprAdminPortEnum 
MprAdminPortGetinfo 
MprAdminReleaselpAddress 
MprAdminUserGetinfo 
MprAdminUserSetinfo 


Although the RRAS functions are similar to their Windows NT 4.0 RAS counterparts in 
functionality, RRAS functions often take a different set of parameters. See the reference 
page for a particular function for complete information on that function’s parameter list. 


The RRAS redistributable for Windows NT 4.0 adds the following functions, which have 
no counterparts in Windows NT 4.0 RAS: 


MprAdminAcceptNewLink 


MprAdminConnectionClearStats 


MprAdminConnectionEnum 
MprAdminConnectionGetinfo 
MprAdminGetPDCServer 
MprAdminisServiceRunning 


MprAdminLinkHangupNotification 


MprAdminPortReset 
MprAdminServerConnect 
MprAdminServerDisconnect 
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In addition to the preceding functions, Windows 2000 adds the following functions: 


MprAdminSendUserMessage 
MprAdminAcceptNewConnection2 
MprAdminConnectionHangupNotification2 


RAS Administration Functions 


This documentation describes RRAS functions that are used to develop software to 
administer RAS dial-up connections. These functions include: 
MprAdminConnectionClearStats 
MprAdminConnectionEnum 
MprAdminConnectionGetinfo 
MprAdminPortClearStats 
-MprAdminPortDisconnect 
-MprAdminPortEnum 
MprAdminPortGetinfo 
MprAdminPortReset 


Additional functions are used for both RAS administration and router administration. 
These functions are listed following and are documented in the Router Administration 
Functions reference: . 

MprAdminBufferFree 

MprAdminGetErrorString 

MprAdminlsServiceRunning 

MprAdminServerConnect 

MprAdminServerDisconnect 


MprAdminConnectionClearStats 


The MprAdminConnectionClearStats function resets the statistics counters for the 
specified connection. 
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Parameters 


hRasServer — | | 
Handle to the Remote Access Server on which to execute 
MprAdminConnectionClearStats. Obtain this handle by calling 
MprAdminServerConnect. 


hRasConnection 
Handle to the connection for which to reset the statistics. Obtain this handle by calling 
MprAdminConnectionEnum. 


Return Values — 
If the function succeeds, the return value is NO_ERROR. 


If the function fails, the return value is ERROR_INVALID_ PARAMETER. 


Remarks 


This function is available on Windows NT 4.0 if the RRAS redistributable is installed. 
However, the version of Mprapi.dll that ships with the RRAS redistributable exports the 
function as RasAdminConnectionClearStats rather than 
MprAdminConnectionClearStats. Therefore, when using the RRAS redistributable, 
use LoadLibrary and GetProcAddress to access this function. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Mprapi.h. 

Library: Use Mprapi.lib. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminConnectionEnum, MprAdminServerConnect 


MprAdminConnectionEnum 


The MprAdminConnectionEnum function enumerates all active connections. 
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Parameters 


hRasServer 
Handle to the Remote Access Server on which connections are enumerated. Obtain 
this handle by calling MprAdminServerConnect. 


dwLevel 
Specifies the format of the information returned through the /p/pbBuffer parameter. 


Windows NT 4.0: This parameter must be zero. 


Windows 2000 and later: This parameter should be zero, one, or two, corresponding 
to RAS_CONNECTION_0, RAS_CONNECTION_1, or RAS_CONNECTION_2. 


lplobBuffer 
Upon successful execution, /o/obBuffer points to an array of structures that describe 
the enumerated connections. These structures are of type RAS_CONNECTION_O, 
RAS_CONNECTION_1, or RAS_CONNECTION_ 2 depending on the value of the 
dwLeve! parameter. Free this memory by calling MprAdminBufferFree. 


dwPrefMaxLen 
Preferred maximum length of returned data (in 8-bit bytes). If dwPrefMaxLen i is -1, the 
buffer returned is large enough to hold all available information. 


IpdwEntriesRead 
Pointer to a DWORD variable. Upon successful return, this variable contains the total 
number of connections enumerated from the current resume position. 


lpdwT otalEntries 
Pointer to a DWORD variable. Upon successful return, this variable contains the total 
- number of connections that could have been enumerated from the current resume 
~ position. 


lpdwResumeHandle- 
Pointer to a DWORD variable. Upon successful return, this variable contains a 
resume handle that can be used to continue the enumeration. The 
IpdwResumeHandle parameter should be zero on the first call, and left unchanged on 
subsequent calls. If the return code is ERROR_MORE_DATA, another call may be 
made using this handle to retrieve more data. If the handle is NULL upon return, the 
enumeration cannot be continued. This handle i is invalid for other types of error 
returns. 
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Return Values 


lf the function succeeds, the return value is NO_ERROR. 


If the function fails, the return value is one of the following error codes. 


Value 


ERROR_INVALID_LEVEL 
ERROR_INVALID_PARAM eres 
ERROR_MORE_DATA 
RPC_S_INVALID_BINDING 


Remarks 


Meaning 


The value passed for dwLevel is not zero, one, or two. 
Levels one and two are supported only on Windows 2000 
and later operating systems. 7 


At least one of the following parameters is NULL or does 
not point to valid memory: /p/oBuffer, lodwEntriesRead, or 
lodwTotalEntries.. 


Not all of the data was returned with this call. To obtain 
additional data, call the function again using the resume 
handle. 


The handle passed in the hRasServer parameter is NULL 


or invalid.. 


This function is available on Windows NT 4.0 if the RRAS redistributable is installed. 
However, the version of Mprapi.dll that ships with the RRAS redistributable exports the 
function as RasAdminConnectionEnum rather than MprAdminConnectionEnum. 
Therefore, when using the RRAS redistributable, use LoadLibrary and 
GetProcAddress to access this function. 


Windows NT/2000: Requires Windows 2000. Available a as a 4 redistributable for 
Windows NT 4.0. 
Header: Declared in Mprapi.h. 
Library: Use Mprapi.lib. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminServerConnect, MprAdminBufferFree, RAS_ CONNECTION. 0O 


MprAdminConnectionGetinfo 


The MprAdminConnectionGetinto function provides formation on a specific 


connection. 
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Parameters 


hRasServer 
Handle to the computer on which connection information is gathered. This computer 
should be running RRAS for Windows NT/Windows 2000. Obtain this handle by 
calling MprAdminServerConnect. 

dwLevel 
Specifies the format and content of the returned information. Acceptable values for 
dwLevel are zero or one. A value of zero returns a RAS_CONNECTION_O structure; 
a value of one returns a RAS_CONNECTION_1 structure. 

hConnection — | 
Handle to the connection for which to obtain information. Obtain this handle by calling 
MprAdminConnectionEnum. 

lolobBuffer 
Pointer to a pointer variable that points to a RAS_CONNECTION_0 or 
RAS_CONNECTION_1 structure upon successful execution. Free this memory bey 
calling Mp Damp euietntee: 


Return Values 
If the function succeeds, the return value is NO_ERROR. 


If the function fails, the return value is ERROR_INVALID_ PARAMETER. 


Remarks 


This function is available on Windows NT 4.0 if the RRAS redistributable is installed. 
However, the version of Mprapi.dil that ships with the RRAS redistributable exports the 
function as RasAdminConnectionGetinfo rather than MprAdminConnectionGetinfo. 
Therefore, when using the RRAS redistributable, use LoadLibrary and 
GetProcAddress to access this function. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Mprapi.h. 

Library: Use Mprapi.lib. 
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prAdminPortClearStats 


The MprAdminPortClearStats function resets the statistics for the specified port. 


arameters : 


hRasServer 
Handle to the Remote Access Server on which to clear the statistics for the specified 
port. Obtain this handle by calling MprAdminServerConnect. 


hPort | | 
Handle to the port for which statistics are reset. Obtain this handle by calling 
MprAdminPortEnum. | 


Return Values 
If the function succeeds, the return value is NO_ERROR. | 


If the function fails, the return value is ERROR_INVALID PARAMETER. 


Remarks © 


This function is available on Windows NT 4.0 if the RRAS redistributable is installed. 
However, the version of Mprapi.dll that ships with the RRAS redistributable exports the 
function as RasAdminPortClearStats rather than MprAdminPortClearStats. 
Therefore, when using the RRAS redistributable, use LoadLibrary and 
GetProcAddress to access this function. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Mprapi.h. _ ne | 

Library: Use Mprapi.lib. 
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MprAdminPortDisconnect 


The MprAdminPortDisconnect function disconnects a connection on a specific port. 


Parameters 


hRasServer 
-Handle to the Remote Access Server on which to disconnect the port. Obtain this 
handle by calling MprAdminServerConnect. — 


_ hPort 7 
Handle to the port to disconnect. Obtain this handle by calling MprAdminPortEnum. 


- Return Values 
If the function succeeds, the return value is NO_ ERROR. 


If the function fails, the return value is ERROR_INVALID_PARAMETER. 


Remarks 


This function is available on Windows NT 4.0 if the RRAS redistributable is installed. 
However, the version of Mprapi.dll that ships with the RRAS redistributable exports the 

function as RasAdminPortDisconnect rather than MprAdminPortDisconnect. 
Therefore, when using the RRAS redistributable, use LoadLibrary and 
GetProcAddress to access this function. 


Windows NT/2000: Requires Windows 2000. pvalanl asa redistributable for 
Windows NT 4.0. | 

Header: Declared in Mprapi.h. 

Library: Use Mprapi.lib. 


Remate Access Service Administration Reference, RAS Administration Functions, 
MprAdminServerConnect, Mpreminror entra: 
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MprAdminPortEnum 


| The MprAdminPortEnum function enumerates all active ports in a specific connection, 
or all ports available for use or currently in use by RAS. 


Parameters 


hRasServer 
Handle to the remote access server on which to enumerate ports. Obtain this handle 
by calling MprAdminServerConnect. 


dwLevel 
Specifies the level of information returned in the enumeration. This parameter must 
be zero. 


hConnection 7 | 
Handle to a connection within which the active ports are enumerated. If hConnection 
is INVALID_HANDLE_VALUE, all the ports in use or available for use by RRAS are 
enumerated. Obtain the hConnection handle by calling MprAdminConnectionEnum. 


lolobBuffer - 
Pointer to a pointer variable that will point to an array of RAS_PORT_O structures on 
successful return. Free this memory by calling MprAdminBufferFree. 


dwPrefMaxLen 
Preferred maximum length of returned data (in 8-bit bytes). If dwPrefMaxLen is -1, 
the buffer returned is large enough to hold all available information. | 


IpdwEntriesRead 
Pointer to a DWORD variable. Upon successful return, this variable contains the total 
number of ports enumerated from the current resume position. 


lpdwTotalEntries. 
Pointer to a DWORD variable. Upon successful return, this variable contains the total 
number of ports that could have been enumerated from the current resume position. 


lpdwResumeHandle 
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Pointer to a DWORD variable. Upon successful execution, jodwResumeHandle 
contains a handle that can be used to resume the enumeration. The 
lpdwResumeHandle parameter should be zero on the first call, and left unchanged on 
~subsequent calls. If the return code is ERROR_MORE_DATA, the call may be 
reissued with the handle to retrieve more data. If the handle is NULL upon return, the 
enumeration cannot be continued. This handle is invalid for other types of error 


returns. 


Return Values 


If the function succeeds, the return value is NO. ERROR. 


If the function fails, the return value is one of the following error codes. 


Value 


ERROR_ACCESS_DENIED 
ERROR_DDM_NOT_RUNNING 


ERROR_INVALID_PARAMETER 
ERROR_MORE_DATA 


ERROR NOT SUPPORTED 


Remarks 


Meaning 


The calling application does not have sufficient privileges. 


The Demand Dial Manager (DDM) is not running, possibly 
because the Dynamic Interface Manager (DIM) is 
configured to run only on a LAN. 


At least one of the following parameters is NULL or does 
not point to valid memory: /plpBuffer, |pdwEntriesRead, or 
lpdwTotalEntries. 


Not all of the data was returned with this call. To obtain 


additional data, call the function again using the handle that 


was returned in the jodwResumeHandle parameter. 


The dwLevel/ parameter is not zero. 


_ This function is available on Windows NT 4.0 if the RRAS redistributable is installed. 
However, the version of Mprapi.dll that ships with the RRAS redistributable exports the 
function as RasAdminPortEnum rather than MprAdminPortEnum. Therefore, when 
using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this 
function. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 


Windows NT 4.0. 


Header: Declared in Mprapi.h. 


Library: Use Mprapi.lib. 
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MprAdminPortGetinfo 


The MprAdminPortGetinfo function gets information for a specific port. 


Parameters 


hRasServer | 
Handle to the Remote Access Server computer on which to collect port information. 
Obtain this handle by calling MprAdminServerConnect. 


dwLevel 
Specifies the format and content of the returned information. Acceptable values for 
dwLevel are zero or one. A value of zero will return a RAS_PORT_O structure; a 
value of one will return a RAS_PORT_1 structure. | 


hPort 
Handle to the port for which to collect information. Obtain this handle by calling 
MprAdminPortEnum. 
lplpbBuffer 
Pointer to a pointer variable that will point to a RAS_PORT_0 or RAS_PORT_1 
structure on successful return. Free this memory by calling MprAdminBufferFree. 


Return Values 
If the function succeeds, the return value is NO_ERROR. 


If the function fails, the return value is ERROR_INVALID_ PARAMETER. 


Remarks 


This function is available on Windows NT 4.0 if the RRAS redistributable is installed. © 
However, the version of Mprapi.dll that ships with the RRAS redistributable exports the 
function as RasAdminPortGetinfo rather than MprAdminPortGetinfo. Therefore, when 
using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this 
function. 
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Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Mprapi.h. 

Library: Use Mprapi.lib. 


Remote Access Service Administration Reference, RAS Administration Functions, 
7 MprAdminServerConnect, MprAdminBufferFree, MprAdminPortEnum 


MprAdminPortReset ca te | 


The MprAdminPortReset function resets the communication device attached to the 
specified port. 


Parameters 


hRasServer | » See : 
Handle to the Remote Access Server on which to reset the specified port. Obtain this 
handle by calling MprAdminServerConnect. 


hPort | | | | 
Handle to the port to be reset. Obtain this handle by calling MprAdminPortEnum. 


Return Values 
If the function succeeds, the return value is NO_LERROR. 


If the function fails, the return value is ERROR_INVALID_PARAMETER. 


Remarks | as 

This function is available on Windows NT 4.0 if the RRAS redistributable is installed. 
However, the version of Mprapi.dll that ships with the RRAS redistributable exports the 
function as RasAdminPortReset rather than MprAdminPortReset. Therefore, when 
using the RRAS redistributable, use LoadLibrary and GetProcAddress to access this 
function. | : 
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Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. | 

Header: Declared in Mprapi.h. 

Library: Use Mprapi.lib. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminServerConnect, MprAdminPortEnum 


RAS Admin DLL Functions 


A RAS server administration DLL allows you to customize the following aspects of RAS: 


e Access control for remote access clients 
e Remote access client connection and disconnection event logging 
e Logging and control of IP address allocation to remote access clients. 


A RAS Admin DLL must implement and export all of the following functions: 


MprAdminAcceptNewLink 
MprAdminConnectionHangupNotification 
MprAdminConnectionHangupNotification2 
MprAdminGetlpAddressForUser 
MprAdminLinkHangupNotification 
MprAdminReleaselpAddress 


In addition, the RAS Admin DLL must implement and export either 
MprAdminAcceptNewConnection, and 
MprAdminConnectionHangupNotification 

or 


MprAdminAcceptNewConnection2, and 
MprAdminConnectionHangupNotification2 


lf not all of the required functions are implemented, the remote access service will fail to 
start. 


RAS serializes calls into the administration DLL. A call into one of the DLL’s functions for 
a given RAS client will never be preempted by a call to that function for a different RAS _ 
client; the initial call is guaranteed to complete before RAS calls the function for the other 


Client. Furthermore, serialization extends to certain groups of functions. The IP address 


functions are serialized as a group; a call into either MprAdminGetipAddressForUser 
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or MprAdminReleaselpAddress will block calls into both until the initial call completes. 
Together, the new connection/link and connection/link-hang-up notification functions are 
also serialized as a group. 


Do not call any of the RAS Administration Functions or Ras User Administration 
Functions from inside a callout function. Calls to these functions will not return when 
made from within a callout function. 


MprAdminAcceptNewConnection 


Remote Access Service calls the MprAdminAcceptNewConnection function each time 
a new user dials in and successfully completes RAS authentication. 
MprAdminAcceptNewConnection determines whether the user is allowed to connect. 


Parameters 


pRasConnectionO 
Pointer to a RAS _ CONNECTION __ 0 structure describing this connection: 


pRasConnection1 | 
Pointer to a RAS_CONNECTION_1 structure describing this connection. 


Return Values 


If MprAdminAcceptNewConnection accepts the connection, the return value should be 
TRUE. 


If MprAdminAcceptNewConnection rejects the connection, the return value should be 
FALSE. | 


Remarks 


if MprAdminAcceptNewConnection does not accept the new connection, RAS will not 
call the MprAdminConnectionHangupNotification function. 


Do not call any of the RAS Administration Functions or Ras User Administration | 
Functions from inside MprAdminAcceptNewConnection. Calls to these functions will 
not return when made from within a callout function. 
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Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. a 
Header: Declared in Moprapi.h. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminAcceptNewConnection2, MprAdminConnectionHangupNotification, 
MprAdminConnectionHangupNotification2, RAS_CONNECTION_0O, 

RAS _CONNECTION_1 


MprAdminAcceptNewConnection2 


Remote Access Service calls the MprAdminAcceptNewConnection2 function each 
time a new user dials in and successfully completes RAS authentication. 
MprAdminAcceptNewConnection2 determines whether the user is allowed to connect. 


Parameters 7 a | 


pRasConnectionO 
Pointer to a RAS_CONNECTION_O structure describing this connection. 


pRasConnection1 | | 
Pointer to a RAS_CONNECTION_1 structure describing this connection. 


pRasConnection2 
Pointer to a RAS_CONNECTION_2 structure describing this connection. 


Return Values 


' If MprAdminAcceptNewConnection2 accepts the connection, the return value should 
be TRUE. 


If MprAdminAcceptNewConnection2 rejects the connection, the return value should 
be FALSE. 


Remarks | . _ | 


If MprAdminAcceptNewConnection2 does not accept the new connection, RAS will not 
call the MprAdminConnectionHangupNotification2 function. 
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Do not call any of the RAS Administration Functions or Ras User Administration 
Functions from inside MprAdminAcceptNewConnectionz2. Calls to these functions will 
not return when made from within a callout function. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Mprapi.h. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminConnectionHangupNotification2, RAS _CONNECTION _0, 
RAS _CONNECTION_ 1, RAS_CONNECTION_2 


MiprAdminAcceptNewLink 


RAS calls the MprAdminAcceptNewLink function each time a link is created for a 
particular connection. RAS calls this function once immediately after 
MprAdminAcceptNewConnection returns, and an additional time for every new link 
that is to be used with the connection. foe 


Parameters 


pRasPortO 
Pointer to a RAS __ PORT_ 0 structure that describes the port pein used by the link. 


pRasPort1 
Pointer to a RAS_PORT_1 structure that describes the ioe being used by the link. 


Return Values | | 
If RAS should accept the new link, the return value should be TRUE. 


lf RAS should not accept the new link, the return value should be FALSE. 


Remarks 


If RAS does not accept the new link, RAS will not call the 
| MprAdminLinkHangupNotification function. 


Do not call any of the RAS Administration Functions or RAS User Ncministration: 
Functions from inside MprAdminAcceptNewLink. Calls to these functions will not return 
‘when made from within a Callout function. 7 
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Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 
Header: Declared in Mprapi.h. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminAcceptNewConnection, MprAdminConnectionHangupNotification, 
MprAdminLinkHangupNotification, RAS_PORT_0, RAS_PORT_1 


MprAdminConnectionHangupNotification 


Remote Access Service calls the MprAdminConnectionHangupNotification function 
after the last link for the specified connection has been dismantled. 


Parameters 


pRasConnectiono 
Pointer to a RAS_CONNECTION_O structure describing this connection. 


pRasConnection1 | 
Pointer to a RAS_CONNECTION_1 structure describing this connection. 


* Return Values 
This function does not have a return value. 


Remarks 


Do not call any of the RAS Administration Functions or Ras User Administration 
Functions from inside MprAdminConnectionHangupNotification. Calls to these 
functions will not return when made from within a callout function. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 
Header: Declared in Mprapi.h. 
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MprAdminConnectionHangupNotification2 


Remote Access Service calls the MprAdminConnectionHangupNotification2 function 
after the last link for the specified connection has been dismantled. 


Parameters 


pRasConnection0O 
Pointer to a RAS_CONNECTION_O structure describing this connection. 


pRasConnection1 
Pointer to a RAS_CONNECTION_1 structure eee ng this connection. 


pRasConnection2 
Pointer to a RAS_CONNECTION_2 structure describing this connection. 


Return Values 
This function does not have a return value. 


Remarks 


Do not call any of the RAS Administration Functions or Ras User Administration 
Functions from inside MprAdminConnectionHangupNotification2. Calls to these 
functions will not return when made from within a callout function..- 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Mprapi.h. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminAcceptNewConnection2, MprAdminAcceptNewLink, 
RAS_CONNECTION_0, RAS_CONNECTION_1, RAS_CONNECTION_2 
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MprAdminGetlpAddressForUser 


RAS calls MprAdminGetlpAddressForUser once for each user that requires an IP 
address. RAS calls the function with the IP address that RAS selects for the user. The 
third-party DLL that implements this function may change this address to one of its own 
enpoeing: 


Parameters 


lowszUserName 
Pointer to a Unicode string containing the name of the user requiring an IP address. 


lowszPortName 
Pointer to a Unicode string containing the name of the port on which the user is 
attempting to connect. 


lpdwlpAddress 
Pointer to a DWORD variable. When RAS calls the function, this variable contains 
either the IP address RAS intends to allocate for the user or zero. If the variable 
contains an IP address, the DLL can either accept the address or substitute a different 
one. If the variable contains a zero, the DLL must allocate an IP address for the user. 
If this variable is zero, and the DLL does not allocate an IP address, the user will not 
be able to connect. | 


bNotifyRelease 
Pointer to a BOOL variable. If the DLL sets this variable to , TRUE, RAS will call 
MprAdminReleaselpAddress when the user disconnects. Otherwise, RAS will not 
notify the DLL when this IP address is released. 


Return Values 
If function succeeds, the return value should be NO_ERROR. 


If the function returns anything other than NO_ERROR, RAS will terminate the 
connection. ; 


Remarks | | | 

Do not call any of the RAS Administration Functions or Ras User Administration 
Functions from inside MprAdminGetipAddressForUser. Calls to these functions will 
not return when made from within a callout function. | 
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Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. | ae a fe | 
Header: Declared in Mprapi.h. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminReleaselpAddress 


MprAdminLinkHangupNotification 


RAS calls the MprAdminLinkHangupNotification function whenever a link fora 
particular connection is dismantled. | 


Parameters 


pRasPort0 | 
Pointer to a RAS_PORT_0 structure that describes the port being used by the link. 


pRasPort1 | 
‘Pointer to a RAS_PORT_1 structure that describes the port being used by the link. 


Return Values 
This function does not have a return value. 


Remarks | | 


Do not call any of the RAS Administration Functions or Ras User Administration 
Functions from inside MprAdminLinkHangupNotification. Calls to these functions will 
not return when made from within a callout function. | | 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. > | | os 
Header: Declared in Mprapi.h. 
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MprAdminReleaselpAddress | 


The MprAdminReleaselpAddress function is called when a user disconnects and the 
user’s IP address is about to be released. 


arameters 


lowszUserName 
Pointer to a Unicode string containing the name of the user requiring an IP address. 


lpwszPortName | 
Pointer to a Unicode string containing the name of the port on which the user is 
attempting to connect. 


lpdwlpAddress 
Pointer to a DWORD variable. This variable contains the IP address to be released. 


Return Values 
This function does not have a return value. 


Remarks 


Do not call any of the RAS Administration Functions or Ras User Administration 
Functions from inside MprAdminReleaselpAddress. Calls to these functions will not 
return when made from within a callout function. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 
Header: Declared in Mprapi.h. 


Chapter 12 Remote Access Service Administration 349 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminConnectionHangupNotification, MprAdminGetlpAddressForUser 


RAS User Administration Functions 
Use the following functions to manage dial-up users: 


MprAdminGetPDCServer 
MprAdminSendUserMessage 
MprAdminUserGetinfo 
MprAdminuUserSetinfo 


To obtain a list of current users on a particular domain, use the 
NetQueryDisplaylInformation function. The prototype for this function is in the 
Imaccess.h header file. 


MprAdminGetPDCServer 


The MprAdminGetPDCServer function retrieves the name of the server with the master 
User Accounts Subsystem (UAS) from either a domain name or a server name. Either 
the domain name parameter or the server name parameter may be NULL, but not both. 


Parameters 

lpwsDomainName iat ay 
Pointer to a null-terminated Unicode string that contains the name of the domain to 
which the RAS server belongs. This parameter can be NULL if you are running your 
RAS administration application on a Windows NT/Windows 2000 Server that is not 
participating in a domain. If this parameter is NULL, the JowsServerName parameter 
must not be NULL. | | 


lpwsServerName | | 
Pointer to a null-términated Unicode string that contains the name of the 


Windows NT/Windows 2000 RAS server. Specify the name with leading “\\” 
characters, in the form: \\servername. This parameter can be NULL if the /owsDomain 


parameter is not NULL. 
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lpwsPDCName 
Pointer to a buffer that receives a null-terminated Unicode string containing the name 
of a domain controller that has the user account database. The buffer should be big 
enough to hold the server name (UNCLEN +1). The function prefixes the returned 
_ server name with leading “\\’ characters, in the form: \\servername. 


Return Values 
If the function succeeds, the return value is NO_ERROR. 


If the function fails the return value is one of the following values. | 


Value _ Meaning 
ERROR_NO_SUCH_DOMAIN The domain specified is not valid. 
NERR_InvalidComputer The jowsDomainName is NULL, and 


lpwsServerName parameter is not valid. 


Remarks 


The MprAdminGetPDCServer function can obtain the name of the server with the user 
accounts database given the name of the RAS server, or the name of the domain in 
which the RAS server resides. To get the server name, call the GetComputerName 
function 


If the server name specified by /pszServer is part of a domain, The server returned by 


MprAdminGetPDCServer will be either the primary domain controller or a backup 
domain controller. 


If the server name specified by JoszServer is a stand-alone Windows NT/Windows 2000 
Server (that is, the server or workstation does not participate in a : 
Windows NT/Windows 2000 domain), then the server name itself is returned in the 
lpszUserAccountServer buffer. 


You can then use the name of the user account server in a call to the 
NetQueryDisplaylnformation function to enumerate the users in the user account 
database. You can also use the server name in calls to the MprAdminUserGetinfo and 
alias ie akenate functions to get and set RAS privileges for a speciiied user 
account. — 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 


Windows NT 4.0. 


Header: Declared in Mprapi.h. 
Library: Use Mprapi.lib. 
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MprAdminSendUserMessage 


The MprAdminSendUserMessage function sends a message to the user connected on 
the specified connection. 


Parameters 


~ hConnection | 
Handle to the connection on which the user is connected. Use 
MprAdminConnectionEnum to obtain this handle. 


_ |pwszMessage | 
Pointer to a Unicode string containing the message to the user. 


Return Values | 
If the function succeeds, the return value is NO_ERROR. 


If the function fails, the return value is one of the following error codes. 


Value | | Meaning 

ERROR_ACCESS_DENIED ; The caller does not have ed 
ree privileges. 

ERROR_DDM_NOT_RUNNING The Demand Dial Manager (DDM) i is 


not running, possibly because the 
Dynamic Interface Manager (DIM) is 
configured to run only ona LAN. 


ERROR_INTERFACE_NOT_CONNECTED The hConnection parameter is not 
| io ae ce valid. , 
ERROR_INVALID_PARAMETER The lpwszMessage parameter 

: | ~ is NULL. 
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Windows NT/2000: Requires Windows 2000. 
Header: Declared in Mprapi.h. 
Library: Use Mprapi.lib. 
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MprAdminUserGetinfo | 


The MprAdminUserGetinfo function retrieves all RAS information for a particular user. 


Parameters 


lowsServerName | | 
Pointer to a Unicode string containing the name of the server computer with the 
master User Accounts Subsystem (UAS). If the remote access server is part of a 
domain, the computer with the UAS will be either the primary domain controller or the 
backup domain controller. If the remote access server is not part of a domain, then 
the server itself will store the UAS. In either case, call the MprAdminGetPDCServer 
function to obtain the value for this parameter. 


If the server itself stores the UAS, this parameter may be NULL. 


lowsUserName 
_ Pointer to a Unicode string containing the name of the user for which to get RAS 


information. 


dwLevel | 
This parameter must be zero. 


Windows 2000 and later: This parameter may be zero or one. 


lpbBuffer | 
Pointer to a RAS_USER_0 structure. The caller must allocate (and free) the memory 


for this structure. Upon successful return, this structure contains the RAS data for the 
specified user. 


Windows 2000 and later: If the dwLeve/ parameter specifies one, /obBuffer should 
point to a RAS_USER_1 structure. 
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Return Values 
If the function succeeds, the return value is NO_ERROR. 


If the function fails the return value is one of the following values. 


Value ; Meaning | 

ERROR_ACCESS_DENIED The caller does not have sufficient privileges. 

ERROR_INVALID_LLEVEL © The value of dwLevel is invalid. 

ERROR_INVALID_PARAMETER IpbBuffer is NULL 

ERROR_NO_SUCH_USER The user specified by jowsUserName dogs not 
exist on the server specified by 
lowsServerName. 

Remarks 


This function is available on Windows NT 4.0 if the RRAS redistributable is installed. 
However, the version of Mprapi.dll that ships with the RRAS redistributable exports the 
function as RasAdminUserGetinfo rather than MprAdminUserGetinfo. Therefore, 

-when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access 
this function. 


Windows NT/2000: Requires Windows 2000. Available as a rodistibutebie for 
Windows NT 4.0. 

Header: Declared in Mprapi.h. 

Library: Use Moprapi.lib. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminGetPDCServer, MprAdminUserSetinfo, RAS_USER_0 


MprAdminUserSetinfo 


The MprAdminUserSetinfo function sets RAS information for the specified user. 


354 


Volume 4 Remote Access Services 


Parameters 

lowsServerName | 
Pointer to a Unicode string containing the name of the server computer with the 
master User Accounts Subsystem (UAS). If the remote access server is part of a 
domain, the computer with the UAS will be either the primary domain controller or the 
backup domain controller. If the remote access server is not part of a domain, then 
the server itself will store the UAS. In either case, call the MprAdminGetPDCServer 
function to obtain the value for this parameter. | | 
If the server itself stores the UAS, this parameter may be NULL. 

lowsUserName 
Pointer to a Unicode string containing the name of the user for which to set RAS 
information. 

dwLevel 
This parameter must be zero. 


_ Windows 2000 and later: This parameter may be zero or one. 


lpbBuffer 
Pointer to a RAS_USER_0 structure that specifies the new RAS information for the 
user. 


Windows 2000 and later: If the dwLevel parametel specifies one, /obBuffer should 
point to a RAS_USER_1 structure. 


Return Values 
lf the function succeeds, the return value is NO_ERROR. 


lf the function fails, the return value is one of the following values. 


Value Meaning | 
ERROR_ACCESS_DENIED The caller does not have sufficient privileges. 
ERROR _INVALID_LEVEL > The value of dwLevel is invalid. 


ERROR_NOT_ENOUGH_MEMORY There are insufficient resources to complete 
| the operation. 


ERROR_NO_SUCH_USER The user specified by pWeUseNbine does 
not exist on the server specified by 
IpwsServerName. 

Remarks 


This function is available on Windows NT 4.0 if the RRAS redistributable is installed. 
However, the version of Mprapi.dll that ships with the RRAS redistributable exports the 
function as RasAdminUserSetinfo rather than MprAdminUserSetinfo. Therefore, 

when using the RRAS redistributable, use LoadLibrary and GetProcAddress to access 
this function. | 
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Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Mprapi.h. 

Library: Use Mprapi.lib. 


Remote Access Service Administration Reference, RAS Administration Functions, 
MprAdminGetPDCServer, MprAdminUserGetinfo, RAS_USER_0 


RAS Administration Structures 


The RAS Administration Functions use the following structures: 


PPP_ATCP_INFO PPP_NBFCP_INFO 
PPP_CCP_INFO | RAS CONNECTION_0 
PPP_INFO eae ee _ RAS_CONNECTION_1 
PPP_INFO_ 2 ee ae a -RAS_CONNECTION_2 
PPP_IPCP_INFO RAS _PORT_0O 
PPP_IPCP_INFO2 é ~ RAS PORT _1 
PPP_IPXCP_INFO > RAS _USER_0- 


PPP_LCP_INFO | -—s RAS_USER_1 


PPP "ATCP_INFO 


The PPP_ATCP_INFO structure contains the result of a PPP P AppleTalk projection 
operation. 


Members 


dwError 
Specifies the result of the PPP control protocol negotiation. A value of zero indicates — 
success. A nonzero value indicates failure, and is the actual fatal error that occurred 
during the control Prowoeo! negotiation. 


wszAddress 
Specifies a Unicode sng that holds the client’s AppleTalk address on the RAS 
connection. 
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Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 
Header: Declared in Mprapi.h. 


Remote Access Service Administration Reference, RAS Administration Structures, 
PPP_INFO 


PPP_CCP_INFO 


The PPP_CCP_INFO structure contains information that describes the results of a 
Compression Control Protocol (CCP) negotiation. | | 


Members 


dwError | | 
Specifies an error if the negotiation is unsuccessful. 


dwCompressionAlgorithm 
Specifies the compression algorithm that the local computer is using. The following 
table shows the possible values for this member. 


Value Meaning 
| RASCCPCA_MPPC Microsoft Point-to-Point Compression (MPPC) Protocol 
RASCCPCA_STAC —__ STAC option 4 | 
dwOptions 


Specifies the compression options on the local computer. The following options are 
supported: | 
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Option | Meaning 
PPP_CCP_COMPRESSION Compression without encryption. 
PPP_CCP_HISTORYLESS Microsoft Point to Point Encryption (MPPE) 


in stateless mode. The session key is 
changed after every packet. This mode 
improves performance on high latency 
networks, or networks that experience 
significant packet loss. 


PPP_CCP_ENCRYPTION40BITOLD —- MPPE using 40-bit keys. 


PPP_CCP_ENCRYPTION4OBIT MPPE using 40-bit keys. 
PPP_CCP_ENCRYPTIONS6BIT MPPE using 56-bit keys. 
PPP_CCP_ENCRYPTION128BIT MPPE using 128-bit keys. 


dwRemoteCompressionAlgorithm 


Specifies the compression algorithm that the remote computer is using. The following 
table shows the possible values for this member. 


Value Meaning 

RASCCPCA_MPPC | Microsoft Point-to-Point el ale 
: (MPPC) Protocol 

RASCCPCA_STAC STAC option 4 


dwRemoteOptions 


Specifies the compression options on the remote computer. The following options are 
supported. 


Option Meaning 
-PPP_CCP_COMPRESSION _ Compression without encryption. — 
PPP_CCP_HISTORYLESS Microsoft Point to Point Encryption (MPPE) 


in stateless mode. The session key is 
changed after every packet. This mode 
improves performance on high latency 
networks, or networks that experience 
significant packet loss. 


PPP_CCP_ENCRYPTION40BITOLD —__ MPPE using 40-bit keys. 


PPP_CCP_ENCRYPTION4OBIT MPPE using 40-bit keys. 
-PPP_CCP_ENCRYPTIONS56BIT MPPE using 56-bit keys. 


PPP_CCP_ENCRYPTION128BIT MPPE using 128-bit keys. | 


Windows NT/2000: Requires Windows 2000. 
_ Header: Declared in Mprapi.h. | 


d 


PPP_INFO 


The PPP_INFO structure is used to report the results of the various PPP projection 
operations for a connection. 


Specifies a PPP_NBFCP_INFO structure. 


Specifies a PPP_IPCP_INFO structure. 


Specifies a PPP_IPXCP_INFO structure. — | 


Specifies a PPP_ATCP_INFO structure. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 
Header: Declared in Mprapi.h. | 


Remote Access Service Administration Reference, RAS Administration Structures, 


PPP_ATCP_INFO, PPP_IPCP_INFO, PPP_IPXCP_INFO, PPP_NBFCP_INFO, 
RAS_CONNECTION_1 oe fe 


PPP.INFOS 


The PPP_INFO_2 structure is used to report the results of the various PPP projection 
operations for a connection. : 
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Members 


dweError 
Specifies the result of the PPP control protocol negotiation. A value of zero indicates 


success. A nonzero value indicates failure, and is the actual fatal error that occurred 
during the control protocol negotiation. 


wszAddress 
Specifies a Unicode string that holds the local computer’s IP address for the 


connection. This string has the form a.b.c.d; for example, “11.101.237.71". 


The PPP_IPCP_INFO structures provides address information from the perspective of 
the server. For example, if a remote access client is connecting to a RAS server, this 
member holds the IP address of the server. 


wszRemoteAddress 
Specifies a Unicode string that holds the IP address of the remote computer. This 


string has the form “a.b.c.d”. If the address is not available, this member is an empty 
string, “”. 

The PPP_IPCP_INFO structures provides address information from the perspective of 
the server. For example, if a remote access client is connecting to a RAS server, this 


member holds the IP address of the client. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 


Windows NT 4.0. 
Header: Declared in Mprapi.h. - | 


Remote Access Service Administration Reference, RAS Administration Structures, 
PPP_INFO, PPP_IPCP_INFO2 


PPP_IPCP_INFO2. 


The PPP_IPCP_INFO2 structure contains the result of a PPP Internet Protocol (IP 
negotiation. 


Chapter 12 Remote Access Service Administration 361 


Members 

dwError 
Specifies the result of the PPP control protocol negotiation. A value of zero indicates 
success. A nonzero value indicates failure, and is the actual fatal error that occurred 
during the control protocol negotiation. 


wszAddress 
Specifies a Unicode string that holds the local computer’s IP address for the 
connection. 


The PPP_IPCP_INFQO2 structures provides address information from the perspective 
of the server. For example, if a remote access client is connecting to a RAS server, 
this member holds the IP address of the server. 


wszRemoteAddress 
Specifies a Unicode string that holds the IP address of the remote computer. If the 
address is not available, this member specifies an empty string, “”. 


The PPP_IPCP_INFO2 structures provides address information from the perspective 
of the server. For example, if a remote access client is connecting to a RAS server, 
this member holds the IP address of the client. 

dwOptions | 
Specifies IPCP options for the local computer. Currently, the only option is 7 
PPP_IPCP_VJ. This option indicates that IP datagrams sent by the local computer 
are compressed using Van Jacobson compression. 2 


dwRemoteOptons 
Specifies IPCP options for the remote peer. Currently, the only option is . 
PPP_IPCP_WVJ. This option indicates that IP datagrams sent by the remote peer (that 
is, received by the local computer) are compressed using Van Jacobson 
compression. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Mprapi.h. 


Remote Access Service Administration Reference, RAS Adeainistration Structures, 
PPP_INFO, PPP_IPCP_INFO 


PPP_IPXCP_INFO 


The PPP_IPXCP_INFO structure contains the result of a PPP intermetwork Packet 
Exchange (IPX) projection operation. 
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PPP_LCP_INFO 


The PPP_LCP_INFO structure contains information that describes the results of an PPP 


Link Control Protocol (LCP) negotiation. 
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Members 
dwError 


Specifies the error that occurred if the negotiation was unsuccessful. 
dwAuthenticationProtocol 


Specifies the authentication protocol used to authenticate the local computer. This 
member can be one of the following values. 


Value Meaning 
PPP_LCP_PAP 
PPP_LCP_SPAP 
PPP_LCP_CHAP 
PPP_LCP_EAP 


Password Authentication Protocol 

Shiva Password Authentication Protocol 
Challenge Handshake Authentication Protocol 
Extensible Authentication Protocol 
dwAuthenticationData 


Specifies additional information about the authentication protocol specified by the 
dw AuthenticationProtocol member. This member can be one of the following 


values. 

- Value Meaning 
PPP_LCP_CHAP_MD5 ~ MD5 CHAP. 
PPP_LCP_CHAP_MS _. Microsoft CHAP 
PPP_LCP_CHAP_ MSV2 Microsoft CHAP version 2 


| dwRemoteAuthenticationProtocol | 


~ Specifies the authentication protocol used to authenticate the remate computer. See 
the dwAuthenticationProtocol member for a list of possible values. 
dwRemoteAuthenticationData 
Specifies additional information about the authentication protocol specified by 


dwRemoteAuthenticationProtocol. See the dwAuthenticationData member for a 
list of possible values. 


dwTerminateReason 
This member always has a value of zero. 
dwRemoteTerminateReason 7 
This member always has a value of zero. 
dwOptions 


Specifies information about LCP options in use by the local computer. This member! is 
a combination of the following flags. 


Flag Meaning 
PPP_LCP_MULTILINK_FRAMING 
RASLCPO_PFC 


RASLCPO_ACFC 


The connection is using multilink 
Protocol Field Compression 
Address and Control Field Compression 


(continued) 
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(continued) 


Flag | Meaning 
RASLCPO_SSHF 

RASLCPO_DES_56 DES 56-bit encryption 
RASLCPO_3_DES Triple DES Encryption 


dwRemoteOptions 
Specifies information about LCP options in use by the remote computer. This member 
is a combination of the following flags. 


Flag Meaning 
_ PPP_LCP_MULTILINK_FRAMING The connection is using multilink. 

RASLCPO_PFC Protocol Field Compression (see RFC 1172) 

RASLCPO_ACFC Address and Control Field Compression 
(see RFC 1172) 

RASLCPO_SSHF Short Sequence Number Header Format 
(see RFC 1990) 

RASLCPO_DES_56 DES 56-bit encryption 

RASLCPO_3_DES | Triple DES Encryption 

dwEapTypeld 


Specifies the type identifier of the Extensible Authentication Protocol (EAP) used to 
authenticate the local computer. The value of this member is valid only if 
dwAuthenticationProtocol is PPP_LCP_EAP. 


dwRemoteEapTypeld 
Specifies the type identifier of the Extensible Authentication Protocol (EAP) used to 
authenticate the remote computer. The value of this member is valid only if 
dwRemoteAuthenticationProtocol is PPP_LCP_EAP. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Mprapi.h. 


PPP_CCP_INFO 


PPP_NBFCP_INFO 


The PPP_ NBFCP__ INFO structure contains the result of a PPP NetBEUI Framer (NBF) 
projection operation. 
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Members | - 
dwError 


Specifies the result of the PPP control protocol negotiation. A value of zero indicates 


| success. A nonzero value indicates failure, and is the actual fatal error that occurred 
during the control protocol negotiation. 


wszWksta 


Specifies a Unicode string that is the local workstation’s computer name. This unique 


computer name is the closest NetBIOS equivalent to a client's NetBEUI address on a 
remote access connection. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. at 


Header: Declared in Mprapi.h. e 2 


| Remote Access Service Administration Reference, RAS Administration Structures, 
PPP_INFO } - 


RAS CONNECTION O 3 3=—™ 


The RAS_CONNECTION_0 structure contains general information regarding a specifi 
connection, such as user name or domain. For more detailed information about a 
specific connection, such as bytes sent or received, see RAS_CONNECTION_1. | 


366 


Volume 4 Remote Access Services 


Members 


~ hConnection 


Handle to the connection. 
hinterface 

Handle to the interface. 
dwConnectDuration 

Specifies the duration of the current connection, in seconds. 
dwinterfaceType 

Specifies the interface type of the current connection. 


_ dwConnectionFlags 


Specifies one of a set of flags that describe this connection. This member can contain 
the following flags. 


Flag ; = Meaning 


RAS_FLAGS_PPP_CONNECTION | The connection is using 
Point-to-Point Protocol (PPP). 
RAS_FLAGS_MESSENGER_PRESENT The messenger service is active on 
| the client, and that messages can be 
sent to the client using 
MprAdminSendUserMessage. 
RAS_FLAGS_RAS_CONNECTION —=—~—~—__—‘ The connection is a NetBIOS 
connection from a Windows 3.11 or 
| Windows for Workgroups client. 
~ RAS_FLAGS_ARAP_CONNECTION - The connection is using AppleTalk 
. | Remote Access Protocol (ARAP). 


wszinterfaceName | 
Specifies a unicode string that contains the name of the interface for this connection. 


wszUserName : 
Specifies a unicode string that contains the name of the user that is logged on to the 
connection. 

wszLogonDomain | 
Specifies a unicode string that contains the domain which the connected user is 
logged onto. 

wszRemoteComputer 
Specifies a unicode string that contains the name of the remote computer, 


Windows NT/2000: Requires Windows 2000. Available as a redistributable fer 
Windows NT 4.0. 


Header: Declared in Mprapi.h. 
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dwCrcErr 
Specifies the CRC (Cyclic Redundancy Check) errors on the current connection. 


dwTimeoutErr 
Specifies the time-out errors on the current connection. 


dwAlignmentErr 
| Specifies the alignment errors on the current connection. 


dwHardwareOverrunErr 
Specifies the number of hardware overrun errors on the current connection. 


dwFramingErr 
Specifies the number of framing errors for the current connection. 


dwBufferOverrunErr | 
Specifies the number of buffer overrun errors. 


dwCompressionRatioln 
Specifies a percentage that indicates the degree to which data received on this 
connection is compressed. The ratio is the size of the compressed data divided by the 
size of the same data in an uncompressed state. 


dwCompressionRatioOut | 
Specifies a percentage that indicates the degree to which data transmitted on this 
connection is compressed. The ratio is the size of the compressed data divided by the 
| size of the same data in an uncompressed state. 


a 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 7 , 
Header: Declared in Mprapi.h. 


ae 


Remote Access Service Administration Reference, RAS Administration Structures, 
RAS CONNECTION_0, RAS: CONNECTION 2, PPP_INFO 


RAS CONNECTION 2 


The RAS_CONNECTION_2 structure contains information for a connection, including 
the GUID that identifies the connection. 
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Members 


hConnection 
Handle to the connection. 


wszUserName[ UNLEN + 1 ] 
Specifies a unicode string that contains the name of the user on this connection. 


dwinterfaceType 
Specifies the type of interface. 


guid | 
Specifies a GUID (Globally Unique |IDentifier) that identifies the connection. For 
incoming connection, this GUID is valid only as long as the connection is active. 


Pppinfo2 
Specifies a PPP_INFO_2 structure that contains information about the PPP 


negotiation for this connection. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Mprapi.h. 


Remote Access Service Administration Reference, RAS Administration Structures, 
MprAdminConnectionEnum, RAS_CONNECTION_0, RAS_CONNECTION_1 


RAS_PORT_0 


The RAS PORT_0 structure contains general information regarding a specific RAS port, 
such as port condition and port name. For more detailed information about a specific 


port, such as line speed or errors, see RAS_PORT_1. — 


; (continued) 
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(continued) 


Members 
hPort 
Handle to the port. 


hConnection 
_ Handle to the connection. 


dwPortCondition 
RAS_PORT_CONDITION structure. 


dwTotalNumberOfCalls | 
Specifies the cumulative number of calls this port has serviced. 


dwConnectDuration 
Specifies the duration of the current connection, in seconds. 


wszPortName 
Specifies the port name. 


wszMediaName 
Specifies the media name. 


wszDeviceName 
Specifies the device name. 


: wszDevice lype 
Specifies the device type. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service Administration Reference, RAS Administration Structures, 
RAS_PORT_1, RAS_PORT_CONDITION 


RAS PORT 1 ee | 


The RAS_PORT_1 structure contains detailed information regarding a specific RAS port, 
such as line speed or errors. For more general information about a port, such as port 
condition or port name, see RAS_PORT_O. 


Handle to the port. 


hConnection 
Handle to the connection. 


dwHardwareCondition 
Specifies a RAS _HARDWARE_CONDITION structure. 


dwLineSpeed 
Specifies the line speed of the port, represented in bits per second. 


dwBytesXmited | | 
Specifies the bytes transmitted on the port. ame 


dwBytesReved ee 
Specifies the bytes received on the port. 


dwFramesXmited | 
Specifies the frames transmitted on the port. : ee 


dwFramesRcved 
Specifies the frames received on the port. 


dwCrcErr | gat 
_ Specifies the CRC errors on the port. 


dwTimeoutErr st 
Specifies the time-out errors on the port. 


dwAlignmentErr Rainey 
- Specifies the alignment errors on the port. 
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dwHardwareOverrunErr 
Specifies the hardware overrun errors on the port. 


dwFramingErr 
Specifies the framing errors on the port. 


‘dwBufferOverrunErr | 
Specifies the buffer overrun errors on the port. 


dwCompressionRatioin 
Specifies a percentage that indicates the degree to which data received on this 
connection is compressed. The ratio is the size of the compressed data divided by the 
size of the same data in an uncompressed state. 


dwCompressionRatioOut 
specifies a percentage indicating the degree to which data transmitted on this 
connection is compressed. The ratio is the size of the compressed data divided ey the 
size of the same data in an uncompressed state. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Access Service Administration Reference, RAS Administration Structures, 
RAS _ PORT_0, RAS HARDWARE_CONDITION 


RAS_USER_0 


The RAS_USER_0 structure contains information for a particular Remote Access - 
Service user. 


Members 


bfPrivilege 
Specifies the types of remote access privilege available to the RAS user. 
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The following remote access privilege constants are defined in Mprapi.h. 


Value — | Meaning 

RASPRIV_DialinPrivilege The user has permission to dial-in to the RAS 
| | server. - “3 3) 

RASPRIV_NoCallback The RAS server will not call back the user to 


establish a connection. 


RASPRIV_AdminSetCallback When the user calls, the RAS server hangs up and 
calls a preset call-back phone number stored in the 
user account database. The wszPhoneNumber 
member of the RAS_USER_0 structure contains 
the user’s call-back phone number. 


-RASPRIV_CallerSetCallback When the user calls, the RAS server provides the 
option of specifying a call-back phone number. The 
user can also choose to connect immediately 
without a call back. The wszPhoneNumber 
member contains a default number that the user 
can override. 


Use the following constant as a mask to isolate the call-back privilege. (This constant 
is also defined in Mprapi.h.) 


RASPRIV_CallbackType 
wszPhoneNumber 


Pointer to a Unicode string containing the phone number at which the RAS user 
should be called back. 


Windows NT/2000: Requires Windows NT 4.0 or later. 
Header: Declared in Rassapi.h. 


Remote Aonees Service Administration Reference, RAS Administration Sr iiee. 
MprAdminUserGetinfo, MprAdminUserSetinfo, RAS_USER_1 


RAS _USER_1 
The RAS_USER_1 structure contains information for a particular Remote Access 


Service user. The RAS_USER_1 structure is similar to the RAS_USER_0 structure, 
except that RAS_USER_1 supports an additional member, bfPrivilege2. 
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Members 
bfPrivilege 
Specifies the types of remote access privilege available to the RAS user. 


The following remote access privilege constants are defined in Mprapi.h. 


Value — _ Meaning | > 
RASPRIV_DialinPrivilege The user has permission to dial-in to the RAS 
| server. 

RASPRIV_NoCallback | The RAS server will not call back the user to 


establish a connection. 


RASPRIV_AdminSetCallback When the user calls, the RAS server hangs up 
and calls a preset call-back phone number 
stored in the user account database. The 
wszPhoneNumber member of the | 
RAS_USER_0 structure contains the user’s call- 
back phone number. 


RASPRIV_CallerSetCallback © When the user calls, the RAS server provides 
the option of specifying a call-back phone 
number. The user can also choose to connect 

J immediately without a call back. The 
| wszPhoneNumber member contains a default 
number that the user can override. 


Use the following constant as a mask to isolate the call back privilege. (This constant 
is also defined in Mprapi.h.) | 


RASPRIV_CallbackType 


wszPhoneNumber | 
Pointer to a Unicode string containing the phone number at which the RAS user 
should be called back. | | 


bfPrivilege2 | aes 
Specifies flags specifying additional remote access privileges that are available to the | 
RAS user. de | 
The following remote access privilege constants are defined in Mprapi.h. 
Value | | Meaning | 
RASPRIV2_DialinPolicy Be Remote access policies determine whether the 


user is allowed dial-in access. 
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Windows NT/2000: Requires Windows 2000. 
Header: Declared in Mprapi.h. 


Seo 
a 


Remote Access Service Administration Reference, RAS Administration 1 Structures, 
MprAdminUserGetinfo, MerhdminUsersetnte: RAS_USER_0 


RAS Administration Enumerated Types 


The RAS Administration Functions use the following enumerated types: 


| RAS_HARDWARE_CON DITION 
RAS_PORT_CONDITION 


RAS_ HARDWARE _CONDITION — 


The RAS_ HARDWARE. CONDITION enumeration type specifies hardware status 
information about a given RAS port. 


Values | 
RAS _ HARDWARE __ OPERATIONAL 
The port is operational. 


RAS_HARDWARE_FAILURE 
The port is not operational, due to a hardware failure. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
~ Windows NT 4.0. 


Header: Declared in Mprapi-h. 


Remote Access Senlcs Administration Reference, RAS ‘Administration Enumerated 
Types 
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CHAPTER 13 


Extensible Authentication 
Protocol (EAP) 


EAP Overview 


Microsoft® Windows® 2000 supports the Extensible Authentication Protocol (EAP). EAP 
allows third-party authentication modules to interact with the implementation of the Point- 
to-Point Protocol (PPP) included in Windows 2000 Remote Access Service (RAS). 


EAP is an extension to PPP, providing a standard support mechanism for authentication 
schemes such as token cards, Kerberos, Public Key, and S/Key. EAP has been made 
available in response to increasing demand to augment RAS authentication with third- 
party security devices. | 


EAP is fully supported on both the Windows 2000 Dial-Up Server and the Dial- -Up 
Networking Client. EAP is a critical technology component for secure Virtual Private 
Networks (VPN), protecting them against iets force” or pocienaly attacks and | 
password guessing. 


EAP improves on previous authentication protocols such as Password Authentication 
Protocol (PAP) and Challenge Handshake Authentication Protocol (CHAP). 
Windows 2000 supports these earlier authentication protocols as well. 


EAP and Internet Authentication Service 


The Extensible Authentication Protocol (EAP) is supported on RAS servers running 
Microsoft® Windows® 2000. It is also supported on Windows 2000 Servers running | 
Internet Authentication Service (IAS). IAS provides remote authentication services using 
Remote Access Dial-In User Service (RADIUS). The following documentation is 
applicable to implementing an EAP on a RAS server or on an IAS server. If you are 
implementing EAP on IAS, simply treat references to RAS as though they refer to IAS. 


EAP Installation 
~Vendors implement EAPs, also known as authentication protocols, in Dynamic-Link | 
Libraries (DLLs). A DLL for the authentication protocol must reside on both the client and 
server computers. For simplicity, the client and server DLLs may be identical; however, 
this is not a requirement. Also, note that the same DLL may gaa more than one 
authentication protocol. 
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The vendor should provide setup software to install and remove the DLL. The setup 
software should also create the appropriate keys and values for the authentication 
protocol in the system registry. The installation of each EAP DLL should create the 
following registry key. 


HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Rasman\PPP\ 
EAP\<eaptypeid> 


In the preceding path, <eaptypeid> is the identifier of the authentication protocol. The 
vendor must obtain this identifier from the Internet Assigned Numbers Authority (IANA). 


The setup software should remove this key when uninstalling the DLL. The eal 
removes this key if the user uninstalls RAS. 


For a description of the supported values for this me see Authentication Protocol 
Registry Values. 


Authentication Protocol Registry Values 

The setup software for the EAP DLL may create the following registry values below 

<eaptypeid>. These registry values are defined in the Raseapif.h header file. The 

RAS_EAP_VALUENAME_PATH and RAS_EAP_VALUENAME_FRIENDLY_NAME _ 

values are required. The setup software may create other keys and values as well. 

These could be used by the authentication protocol itself. For an example of registry 

configuration, see Registry Values Example. 
RAS_EAP_VALUENAME_PATH 
RAS_EAP_VALUENAME_FRIENDLY_NAME 
RAS_EAP_VALUENAME_CONFIGUI 
RAS_EAP_VALUENAME_DEFAULT_DATA 
RAS_EAP_VALUENAME_REQUIRE_CONFIGUI 
RAS_EAP_VALUENAME_CONFIG_CLSID 

~ RAS_EAP_VALUENAME_IDENTITY 

RAS_EAP_VALUENAME_INTERACTIVEUI 
RAS_EAP_VALUENAME_INVOKE_NAMEDLG 
RAS_EAP_VALUENAME_INVOKE_PWDDLG 
RAS_EAP_VALUENAME_ENCRYPTION 
RAS_EAP_VALUENAME_STANDALONE_SUPPORTED 


RAS_EAP_VALUENAME_PATH 
Constant Value Path | 
Type REG_ EXPAND. _SZ . 
Description Specifies the path to the EAP DLL. 
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RAS _EAP_VALU ENAME_FRIENDLY NAME 


Constant Value FriendlyName 

Type REG_SZ 

Description — _ Specifies a friendly name for the authentication protocol. 
This name will appear in the Dial-Up Networking user 
interface. 


RAS_EAP_VALUENAME_CONFIGUI 


Constant Value ~ ConfigUIPath | 
Type REG_EXPAND_SZ 
Description | Specifies the path to the DLL that implements the 


configuration user interface. 


RAS_EAP_VALUENAM E DEFAULT DATA | 


Constant Value ConfigData 

Type REG_BINARY 

Description Specifies default configuration data for the Juthentication 
protocol. 


RAS EAP _VALUENAME_REQUIRE_CONFIGUI 


Constant Value RequireConfigUI 
Type. REG_DWORD | 
Description Specifies whether the user must ‘provide configuration 


data in the Dial-Up Networking user interface. If this 
value is 1, the user will not be allowed to exit the Dial-Up 
Networking UI without providing configuration data. The 
default value is 0. 


RAS_EAP_VALUENAME_CONFIG_CLSID 


Constant Value ConfigCLSID 

Type REG_SZ | 

Description | Specifies the class identifier of the configuration Ul on the 
| server. 


RAS _EAP_VALUENAME IDENTITY 


Constant Value a IdentityPath = 
Type 7 ~  REG_EXPAND_SZ 


Description | _. Specifies the path to the DLL that mprements functions to 
a _ obtain the user’s identity. : 
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RAS_EAP_VALUENAME_INTERACTIVEUI 


Constant Value 


Type 
Description 


_InteractiveUIPath 
, REG_EXPAND_SZ | 
Specifies the path to the DLL that implements th 


interactive user interface. 


RAS_EAP_VALUENAME_INVOKE_NAMEDLG 


Constant Value 


Type 
Description 


InvokeUsernameDialog 

REG_DWORD_ 

Specifies whether the RAS Connection Manager should 
display the standard Windows NT/2000 user name dialog 
(value of 1) or invoke RasEapGetldentity (value of 0). 
The default value is 1. 


RAS EAP_VALUENAME_INVOKE_PWDDLG 


Constant Value 


Type 
Description 


InvokePasswordDialog 

REG_DWORD 

Specifies whether the RAS Connection Manager should 
display the standard Windows NT/2000 password dialog. 
If this value exists and is 0, RAS will not display the 
password dialog. The default value is 1. 


RAS _EAP_VALUENAME_ENCRYPTION 


Constant Value 


Type 
Description 


MPPEEncryptionSupported 
REG_DWORD 
If this value is 1, the authentication protocol can generate 


_ keys for the Microsoft Point-to-Point Encryption (MPPE) 


Style of encryption. Possible values are 0 or 1. The 
default value is 0. , 


RAS_EAP_VALUENAME_STANDALONE_SUPPORTED 


Constant Value 


Type 
Description 


StandaloneSupported 
REG_DWORD 
Specifies whether this authentication protocol is 


supported on stand-alone Windows 2000 servers. A 
value of 0 indicates that the EAP is not supported. The 


default value is 1. 
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Registry Values Example 
The following example shows possible data for some of the authentication protocol 
registry values. 


User Authentication 
The authentication protocol may authenticate the user itself. EAP-TLS is an example of 
such a protocol. Alternatively, the authentication protocol may rely on a separate 
authentication provider to authenticate the user. Two authentication providers are built 
into Microsoft® Windows® 2000: Windows 2000 domain authentication (accessed via 
Directory Services) and RADIUS (Remote Access Dial In User Service). 7 


In the case where RADIUS is the authentication provider, the EAP DLL is installed on 
the RADIUS server rather than on the RAS server. The RAS server passes EAP packets 
directly from the client to the authentication protocol on the RADIUS server. The RAS 
server dogs not process any of the information in the EAP packets. 


_EAP Implementation Details 


Microsoft® Windows® 2000 RAS interacts with EAP implementations through the use of 
function calls that must be exported by the third-party EAP DLL. This interaction is 
detailed in the following topics: 


° RAS Connection Manager Initialization 

e Authentication Protocol Initialization 

e RAS and Authentication Protocol Interaction 
e Completion of the Authentication Session 


RAS Connection Manager Initialization 


_ After initialization, the Remote Access Service (RAS) Connection waniaget queries the 
_ registry for installed authentication protocols. RAS calls the exported function — 
-RasEapGetinfo one time for each authentication protocol. The RasEapGetInfo function 
receives a single parameter of type PPP_EAP_INFO. RAS uses the dwEapTypeld 
member of this structure to specify the authentication protocol (note that a single DLL 
| may support more than one protocol). If RasEapGetinfo returns any value other than 
NO_ERROR, RAS assumes that the authentication protocol is unavailable. 
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On return from RasEapGetinfo the PPP_EAP_INFO structure contains pointers to the 
functions RasEaplnitialize, RasEapBegin, RasEapMakeMessage, and RasEapEnd in 
the EAP DLL. RAS uses these functions to interoperate with the authentication protocol. 
RAS immediately calls RasEaplnitialize for each authentication protocol, to initialize it. 
When RAS shuts down it calls RasEapInitialize again, this time with a value of FALSE, 
indicating that the authentication protocol should shut itself down. 


Authentication Protocol Initialization 


To create a phone-book entry for a particular connection, the user selects an 


~ authentication protocol to use for that connection. The selected authentication protocol 


may require configuration. If so, the Dial-Up Networking user interface (UI) displays a 
configuration Ul by calling the RasEapInvokeConfigUI function. The Dial-Up 
Networking UI stores the configuration information returned by RasEapInvokeConfigUI 
in the phone-book entry. The setup program for the authentication protocol may also 
store default configuration information in the registry. For more information, see EAP 
Installation. 


The configuration information stored in the phone-book entry should be generic to all 
users on the client computer. Information specific to a particular user or users should not 


be stored in the phone-book entry. The authentication protocol should obtain user- 


specific information via the identity function interface or interactive user-interface. The 
authentication protocol can store this information in the registry by passing it to RAS in 
the pEapOutput parameter of RasEapMakeMessage. 


The configuration information should not be specific to the current machine; it should be 
portable from machine to machine. 


When the client attempts to establish the connection, RAS obtains identity information 
for the user. If the RAS_EAP_VALUENAME_INVOKE_NAMEDLG value is present in the 
registry for this authentication protocol, and this value is set to zero, RAS calls 


_ RasEapGetldentity. This function typically displays a user interface that allows the 
_ identity information to be of a type specific to the authentication protocol; for example, a 


certificate or numeric ID. If RAS_EAP_VALUENAME_INVOKE_NAMEDLG is not 
present, or is set to one, RAS displays the standard Windows NTMWindows 2000 
user-name dialog. 


Once RAS has obtained the identity information for the user, RAS calls the 
authentication protocol’s implementation of RasEapBegin. This call allows the protocol 
to allocate and initialize a work buffer that RAS passes on subsequent calls to — 
RasEapMakeMessage and RasEapEnd. In RasEapBegin, RAS also passes a | 
PPP_EAP_INPUT structure that contains pointers to the configuration information for the 
connection, and the identity information for the user. RAS always passes in a value for 


the pszidentity member of PPP _EAP_INPUT. However, the pezfaseword member of 
! PPP_ EAP_INPUT may be NULL. , 


Within the PPP_EAP_INPUT structure, the fAuthenticator member indicates whether 


the authentication protocol is being invoked to be authenticated (on the client) or as the 


authenticator cont the server). 
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On the server, the blInitiallID member of PPP_EAP_INPUT specifies the identifier that 
the server should use for the first EAP packet. The server should increment this identifier 
for subsequent packets. 


Also on the server, the pUserAttributes pointer in PPP_EAP_INPUT points to an array 
of attributes of the RAS_AUTH_ATTRIBUTE_TYPE type. These are attributes for the 
user that were obtained from the client. 


If the RasEapBegin call returns any value other than NO_ ERROR, the session is 
disconnected. The returned error is logged (on the server), or yr displayed to the user 
(on the client). | 


RAS and Authentication Protocol Interaction During Authentication 


The RasEapMakeMessage function controls the majority of the interaction between the 
authentication protocol and the RAS Connection Manager. RasEapMakeMessage 
processes incoming EAP packets and creates EAP packets for transmission to the 
remote peer. It also processes events such as time outs and authentication completion. 


_ Ifa message is received from the remote peer, RAS calls RasEapMakeMessage, 
_ passing a pointer to the received message in the pReceivePacket parameter. 


If RAS calls RasEapMakeMessage with pReceivePacket set to NULL, RAS is either 
initiating the dialog by using the authentication protocol, or requesting that the protocol © 
resend the last packet. The authentication protocol should determine which action RAS | 
is taking based on its state and from the message context. ) 


_ On return from RasEapMakeMessage, the value of the Action member of the 
PPP_EAP_OUTPUT structure indicates what action, if any, RAS should take. The 
Action member takes values from the PPP_EAP_ACTION enumerated type. 


lf Action i is EAPACTION_Send, EAPACTION_ SendAndDone, 

EAPACTION_SendWithTimeout, or EAPACTION _SendWithTimeoutInteractive, the RAS 
Connection Manager transmits the packet that is pointed to Oy the peonge acKer” 
parameter to the remote peer. 


If Action is EAPACTION _SendWithTimeout, or 

~ EAPACTION_SendWithTimeoutinteractive, the authentication srotoco! should set the 
, dwidExpected member of the PPP_EAP_OUTPUT structure to the identifier of the next | 
packet that is expected from the remote peer. Regardless of whether the next packet : 
received from the peer matches this value, RAS passes the packet to the authentication 
protocol in a subsequent call to RasEapMakeMessage. The authentication protocol may 
silently discard the packet by simply returning ERROR_PPP_INVALID_PACKET. If a 
packet that has the expected identifier is not received within the configured time-out 
period, RAS calls RasEapMakeMessage. The call is made with the pReceivePacket 
parameter set to NULL, to indicate that the previous packet must be sent again. 


~The EAPACTION _SendWithTimeout value allows fora time out, after which time the 
RAS Connection Manager Service disconnects the session. 
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The EAPACTION_SendWithTimeoutInteractive value provides for an infinite amount of . 
time out to occur. The authenticator should use this value when expecting user input on 
the client. This time out allows the user an unspecified amount of time to complsie the 
required input. 


lf the Action member is EAPACTION_ Done or EAPACTION_SendAndDone, RAS 
examines the dwAuthResultCode member of PPP_EAP_OUTPUT. If 
dwAuthResultCode is NO_ERROR, the authentication succeeded. If 
dwAuthResultCode is a value other than NO_ERROR, the authentication failed. The 
error code returned for the failure case should come from Raserror.h, Mprerror.h, or 
Winerror.h. Possible return codes include, but are not limited to, the UL 


ERROR_NO_DIALIN_PERMISSION 
ERROR_PASSWD_EXPIRED 
ERROR_ACCT_DISABLED 
ERROR_RESTRICTED_LOGON_HOURS 
ERROR_AUTH_INTERNAL | 


In the case where Action is EAPACTION_Done or EAPACTION_SendAndDone, the 
pUserAttributes member should point to attributes that override attributes of the same 
type that were passed to the server in the call to RasEapBegin. 


The authentication protocol can request that RAS invoke the current authentication 
provider by returning EAPACTION_Authenticate in the Action member in | 
PPP_EAP_ OUTPUT. In this case, the pUserAttributes pointer in PPP_EAP_OUTPUT 
should point only to attributes that were generated by the authentication protocol on the 
server. It need not include any of the attributes that were passed to the server in the call 
to RasEapBegin. When RAS responds to the EAPACTION_ Authenticate action, 
pUserAttributes (in PPP_EAP_INPUT), will point to all attributes generated during 
authentication. These attributes will also be returned to the authentication protocol on 
the client. | 


If the authentication protocol authenticates the user without relying on an authentication 
provider, there is no need for the protocol to ever set Action to 


~ EAPACTION_Authenticate. An example of this case is EAP-TLS. 


The EAP success packet is not acknowledged. Therefore, it may be lost and not resent 
by the server. If the RAS Connection Manager on the client receives a Network Control 


Protocol (NCP) packet, RAS is programmed to proceed as though the authentication 


was successful, but the EAP success packet was lost. This is because the server has 
moved on to the NCP phase of PPP. Accordingly, RAS calls RasEapMakeMessage with 
the fSuccessPacketReceived member of the PPP_EAP_INPUT structure set to TRUE. 


During the course of the authentication session, the authentication protocol may need to 
interact directly with the user on the client. The authentication protocol vendor can 


provide an interactive user interface for this purpose. The authentication protocol can 


request that RAS display the interactive UI by setting the flnvokelnteractiveUl, 
pUIContextData, and dwSizeOfUIContextData members in the PPP_EAP_OUTPUT 
structure. For more information on using an interactive UI, see Interactive User Interface. 
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The authentication protocol should display a user interface only through the mechanism 
described under Interactive User Interface. If the authentication protocol itself displays 
the user interface, the PPP thread blocks until the user interface is dismissed. 


If during the authentication process, RasEapMakeMessage returns any value other than 
NO_ERROR or ERROR_PPP_INVALID_PACKET, the session is Blsconnecicg and the 
_ error is logged (on the server) or displayed to the user (on the client). 


Completion of the Authentication Session 


After the authentication session is completed, the RAS Connection Manager calls the 
RasEapEnd function to allow the authentication protocol to deallocate its work buffer. 
This action is taken regardless of whether authentication was successful. Calling the 
RasEapEnd function guarantees that no further calls are made to the authentication 
protocol using that particular user or context without first calling RasEapBegin. 


Configuration User Interface 


Configuration user interfaces (UI) for authentication protocols are implemented 
differently depending on whether the UI configures the authentication protocol on the 
client, or on the server. The following topics describe the process used to implement a 
configuration UI for the client and for the server: 


e Server-Side Configuration User Interface 
e Client-Side Configuration User Interface . 


_ Server-Side Configuration User Interface 


Implement a configuration UI for the server by implementing the COM interface, 
IEAPProviderConfig. This COM interface derives from IUnknown and adds three 
methods: IEAPProviderConfig::Initialize, 

IEAPProviderContig: -ServerInvokeConfigUI, and IEAPProviderConfig: -Uninitialize. 


The UI should support remote administration. In other words, although the UI will 
configure the authentication protocol on the server, the UI itself may be running on a 
different computer. To support remote administration, separate the Ul code from the 
code that actually performs the configuration. (The configuration code resides on the 
server on which the authentication protocol runs.) 


Microsoft recommends using the Active Template Library (ATL) to implement 
IEAPProviderConfig. See the sample server-side configuration UI in the SDK samples 
directory for more details. The CLSID for the configuration Ul object should be placed in 

_ the registry with a value name of RAS_EAP_VALUENAME_CONFIG_CLSID. (For more 
information, see Authentication Protocol Registry Values.) 


When the user clicks the Configure button for an authentication protocol (in mes 
Properties dialog box for Routing and RAS), the system checks if a 
RAS_EAP_VALUENAME_CONFIG_CLSID for this authentication protocol exists in the 
registry. If so, COM instantiates the configuration UI object. If the system is unable to 
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find RAS_EAP_VALUENAME_CONFIG_CLSID in the registry, and the system has 


access to Directory Services (DS) (Windows 2000 only), the ee attempts to 


instantiate the object from the Class Store. 


In the case where the user is connected to multiple machines simultaneously, multiple 
configuration UI objects are instantiated. 


Client-Side Configuration User Interface 


The vendor that implements the authentication protocol may also provide a configuration 
User Interface (UI) for the protocol. The configuration U] may be implemented in the 
same DLL as the authentication protocol, or in a separate DLL. Also, the DLL that 
implements the configuration Ul may support more than one authentication protocol. The 
path to the DLL for the configuration user interface is stored in the 
RAS_EAP_VALUENAME_CONFIGUI registry value, under the key for the authentication 
protocol. For more information about creating this registry value, see EAP Installation. 


The DLL for the eomnetaton user interface should export entry points for the fevOwinG 


- functions: 


RasEapInvokeConfigUI 
RasEapFreeMemory 


When the user creates a phone-book entry for a particular RAS server inthe | 
Dial-Up-Networking UI, the user is able to select the authentication protocol that RAS 


_ should use with that entry. If the authentication protocol is configurable, the 


Dial-Up-Networking UI calls RasEapInvokeConfigUI to invoke the configuration Ul. The | 
Dial-Up-Networking UI stores the configuration information returned by 
RasEapinvokeConfigUI in the phone-book entry 


The configuration information stored in the phone-book entry should be generic to all 
users on the client computer. Information specific to a particular user or users should not 
be stored in the phone-book entry. The authentication protocol should obtain user- 


specific information by using the identity functions or interactive user-interface. The — 


authentication protocol can store this information in the registry by passing it to RAS in 
the pEapOutput parameter of RasEapMakeMessage. | 


The configuration information should also not be specific to the current machine: it 
should be portable from machine to machine. | 


When RAS calls the RasEapBegin function for the authentication sioloecl it passes a 
PPP_EAP_INPUT structure that contains a pointer to the configuration information. After 
RasEapBegin returns, RAS calls RasEapFreeMemory to free the memory occupied by 
the configuration information. Therefore, the authentication protocol should copy the 
configuration information into a private memory buffer during the call to RasEapBegin. 


The vendor may add a value under the registry key for the authentication protocol that 
specifies default configuration information for the protocol. The vendor may also add a 
value that specifies whether the user is required to enter configuration information when 
they create a phone-book amy: For more information, see Authentication Protocol 
Registry Values. 
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Obtaining Identity Information 


The vendor that implements the authentication protocol may also provide a function 
interface that obtains initial identifying information for the user requesting authentication. 
The vendor should implement the following functions: 


RasEapGetldentity 
RasEapFreeMemory 


These functions may be implemented in the same DLL as the authentication protocol, or 
in a separate DLL. Also, the DLL that implements the identity functions may support 
more than one authentication protocol. The path to the DLL for these functions is stored 
in the RAS_EAP_VALUENAME_IDENTITY registry value, under the key for the 
authentication protocol. For more information about creating this ae value, see EAP 
Installation. — , 


The RasEapGetldentity function typically displays a User Interface (UI) to obtain -oldenitify 
information for the user. However, if the dwFlags parameter contains the 
RAS_EAP_FLAG_NON_INTERACTIVE flag, Ras babeetderiity should not display 

a Ul. 


If RlasEapGetidentity does display a UI, the Utinust etinport WM_COMMAND 
messages where the value of LOWORD(wParam) is equal to IDCANCEL. 


The RAS Connection Manager calls RasEapGetldentity if the 
RAS_EAP_VALUENAME_INVOKE_NAMEDLG value that is in the registry for this EAP 
is set to zero. If RAS_EAP_VALUENAME_INVOKE_NAMEDLG is not present, or is 
present and is set to one, RAS displays the standard Windows NT/Windows 2000 user _ 
name dialog box. 


In addition to RAS__ EAP _VALUENAME _ INVOKE. NAMEDLG, the EAP vendor may 
create a related value in the registry: RAS_EAP_VALUENAME_INVOKE_PWDDLG. 

If this value is present and is set to zero, RAS will not display the standard 

Windows NT/Windows 2000 password dialog. This value can be useful to implement a 
biometric method such as a fingerprint scan to authenticate the user. If both the 
RAS_EAP_VALUENAME_INVOKE_NAMEDLG and 
RAS_EAP_VALUENAME_INVOKE_PWDDLG values are zero, an identity UI can be 
used to obtain both the identity and biometric information. However, if only | 
RAS_EAP_VALUENAME_INVOKE_PWDDLG is zero, RAS will not call 
RasEapGetldentity. In this case, use the interactive user Interiace to obtain the 
biometric information. 


For more information on these registry values, see BUI EAUCSTON Protocol Registry 
Values. 
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The information obtained by RasEapGetldentity is passed to the authentication protocol 
during the call to RasEapBegin. The information is pointed to by the pszidentity and 
pUserData members of the PPP_EAP_INPUT structure. To save this information in the 
registry on the client computer, the authentication protocol should return the information 
in the pEapOutput parameter of RasEapMakeMessage. 


After the call to RasEapBegin, RAS calls RasEapFreeMemory to free the memory 
occupied by this data. Therefore, the authentication protocol should copy the information 
into a private memory buffer during the call to RasEapBegin. 


Interactive User Interface 


The vendor that implements the authentication protocol may also provide an interactive 
User Interface (UI) for the protocol. The interactive Ul allows the authentication protocol 
to obtain additional information from the user as needed during the course of the 
authentication session. 


The interactive UI can be implemented in the same DLL as the authentication protocol, 
or in a separate DLL. Also, the DLL that implements the interactive Ul can support more 
than one authentication protocol. The path to the DLL for the interactive Ul is stored in 
the RAS_EAP_VALUENAME_INTERACTIVEUI registry value, under the key for the 
authentication protocol. For more information about creating this registry value, see EAP 
Installation. 


The DLL for the interactive UI should export entry points for the following functions: 


RasEapInvokelnteractiveUl 
RasEapFreeMemory 


The interactive user interface must support WM_COMMAND messages where 
LOWORD(wParam) equals IDCANCEL. 


To display the interactive UI, the authentication protocol should set the 
flnvokelnteractiveUI member of the PPP_EAP_OUTPUT structure to TRUE. The 


_ authentication protocol may optionally set the pUIContextData and 


dwSizeOfUIContextData members as well. RAS uses the values of these members to 
pass context data to the interactive Ul. The authentication protocol returns this 
PPP_EAP_OUTPUT structure as a parameter in the RasEapMakeMessage function. 


RAS invokes the interactive UI by calling RasEapInvokelnteractiveUI. RAS passes the 
authentication protocol a pointer to the data that was returned by the interactive UI in the 
subsequent call to RasEapMakeMessage. The pointer is passed as a member of a 
PPP_EAP_INPUT structure. After RasEapMakeMessage returns, RAS calls 
RasEapFreeMemory to free the memory occupied by the information. Therefore, the 


authentication protocol should copy the information into a private memory buffer during 


the call to RasEapMakeMessage. 
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Multilink and Callback Connections 


For the first link in a multilink connection, RAS sets the RAS_EAP_FLAG_FIRST_LINK 
flag in the fFlags member of the PPP_EAP_INPUT structure. The authentication 
protocol can use the presence of this flag to determine whether to present a user 
interface specifically for the first link of a multilink connection. 


If the connection is configured so that the server calls back the client computer, the 
RAS_EAP_FLAG_FIRST_LINK flag will not be set on the callback. 


If the authentication protocol sets the fSaveConnectionData member of 
PPP_EAP_OUTPUT to TRUE, subsequent links in the multilink connection will receive 
the new connection-specific data. In the case of user-specific data, however, the 
authentication protocol continues to get the original user-specific data even if it sets the 
fSaveUserData member of PPP_EAP_OUTPUT to TRUE. 


The authentication protocol may use an interactive user interface to collect data for a 
particular link of a multilink connection. In this case, RAS makes the resulting data 
available to the authentication protocol during subsequent links. This data is never saved 
to persistent storage, however. 


~ EAP Reference 


This section describes the reference elements that are used to implement the Extensible 
Authentication Protocol (EAP). Among these reference elements are functions that you | 
can use to program authentication protocols, authentication providers, and accounting 
providers. This section also includes the structures and enumerated types that these 
functions use. 


EAP Functions 
Implement the following functions for authentication protocols and authentication 
providers: 
RasEapBegin : RasEapGetinfo 
RasEapEnd RasEapInvokeConfigUI 
RasEapFreeMemory - RasEapinvokelinteractiveUl 
RasEapGetldentity RasEapMakeMessage 


RasEapBegin 


The Connection ‘Manager calls the RasEapBegin function to initiate an authentication 
session. : 
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Parameters 


ppWorkBuffer 
Pointer to a pointer that, on successful return, points to a work buffer. This buffer is 
opaque to RAS; the contents of the buffer are used only by the authentication | 
protocol. The Connection Manager passes a pointer to this buffer to the authentication 
protocol in subsequent calls to RasEapMakeMessage. | 

pPppEap!/nput | 
Pointer to a PPP_EAP_INPUT structure that contains initialization information for the 
authentication session. 


Return Values ao. 
If the function succeeds, the return value is NO_ERROR. 


lf the function fails, the return value should be an appropriate error code from Winerror.h, 
Raserror.h, or Mprerror.h. 


Remarks 


The RasEapBegin function is not part of the RRAS API; it is implemented in the EAP 
DLL. When the Connection Manager calls the RasEapGetinfo function, it receives a 
PPP_EAP_INFO structure for the authentication protocol. This structure contains a 
pointer to the RasEapBegin function. 


The memory for the work buffer (pointed to by * ppWorkBuffer) is allocated by the 
authentication protocol. The authentication protocol should free this memory in its 
implementation of RasEapEnd. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Functions, RasEapEnd, 
RasEapGetinfo, RasEapMakeMessage, PPP_EAP_INFO, PPP_EAP_INPUT 
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“Raseapend 


The Connection Manager calls the RasEapEnd function to end an authentication 
session. RAS will call RasEapEnd regardless of whether the session completed 
successfully. 


Parameters 


PWorkBuffer 
Pointer to the work buffer to free. 


Return Values | 
If the function succeeds, the return value is NO_ERROR. 


lf the function fails, the return value should be an appropriate error code from Winerror.h, 
Raserror.h, or Mprerror.h. If Haskapend returns an error code, RAS terminates the 
authentication session. 


Remarks 

The RasEapEnd function is ‘not part of the RRAS API: it is pone’. in the EAP DLL. 
When the Connection Manager calls the RasEapGetinfo function, it receives a 

PPP_ EAP_INFO structure for the authentication protocol. This structure contains a 
pointer to the RasEapEnd function. 


Provided that RasEapBegin returned successfully, the Connection manager calls the 
RasEapEnd function when authentication has completed. | 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Functions, RasEapBogin: 
RasFapGetinfo, PPP_EAP_INFO, PPP_ EAP_ INPUT 


‘RasEopFreelemory 


The Connection Manager calls RasEapFreeMemory to free memory buffers returned by 
RasEapInvokeConfigUI, RasEapGetldentity, and RasEapInvokelnteractiveuUl. 
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Parameters 


pMemory 
Pointer to the memory to free. 


Return Values — 
If the function succeeds, the return value is NO_ERROR. 


If the function fails, the return value should be an appropriate error code from Winerror.h, 
Raserror.h, or Mprerror.h. 


Remarks 
An authentication protocol may implement its various user interfaces in different DLLs. In 
such a case, each DLL must implement the RasEapFreeMemory function. 


It is also possible that a single DLL may implement multiple user interfaces. For 
example, a single DLL may implement both the configuration and identity user interface 
for an authentication protocol. Another example would be a DLL that implements two 
configuration user interfaces, each to support a different authentication protocol. In these 
cases, the DLL must implement a single version of RasEapFreeMemory that can free 
memory returned from any of the user interfaces implemented in the DLL. 


sss 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. | 


Extensible Authentication Protocol Reference, EAP Functions, RasEapInvokeConfigUI, 
RasEapGetidentity, RasEapinvokelinteractiveUI 


RasEapGetldentity 


The RAS Connection Manager calls the RasEapGetldentity function to obtain identity 
information for the user requesting authentication. 
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Parameters 


dwEap lypeld 
Specifies the are eton protocol for which to invoke the identity user interface. 


hwndParent 


Handle to the parent window for the user interface dialog. If the dwFlags parameter 
contains the RAS_EAP_FLAG_NON_INTERACTIVE flag, then AhwndParent is NULL. | 


dwFlags 
Specifies zero or more of the following flags that qualify the authentication process. 
Flag Description 
RAS_EAP_FLAG_ROUTER Specifies that the computer that is 


dialing in is a router. The absence of 
this flag indicates that the computer 
dialing in is a RAS client. 


RAS_EAP_FLAG_NON_INTERACTIVE Specifies that the authentication 

i | 7 protocol should not bring up a user- 
interface. If the authentication protocol 
is not able to determine the identity 
from the data supplied, it should return 
an error. If this flag is specified, the 
hwndParent parameter will be NULL. 


RAS_EAP_FLAG_LOGON _ © ee: . Specifies that the user data is obtained 


| from Winlogon. | 
RAS_EAP_FLAG_PREVIEW , _ Specifies that the user should be 


prompted for identity information 
before dialing. 


(continued) 
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~ (continued) 


Flag | | Description | 
RAS_EAP_FLAG_FIRST_LINK Indicates that this connection is the 
first link in a multilink connection. See 
Multilink and Callback Connections for 
more information. 
pwszPhonebook 


Pointer to a Unicode string that contains the full path of the Phone-Book (PBK) file. If 
this parameter is NULL, the function uses the system phone book. 


pwszEntry 
Pointer to a Unicode string that contains an ea entry name. 


pConnectionDataln 
Pointer to the connection-specific data currently stored in the phone-book entry. 


dwSizeOfConnectionDatalIn 
Size of the connection-specific data currently stored in the pone -book entry. 


pUserDataln 
Pointer to the user-specific data currently stored for this user in the registry. 


dwSizeOfUserDataln 
Specifies the size of the user-specific data suirenily stored for this user in the registry. 


ppUserDataOut 
Pointer to a pointer that, on successful return, points to the identity data for the user. 
_ This data will be passed to the authentication protocol in the pUserData member of 
PPP_EAP_INPUT during the call to RasEapBegin. | 


The authentication protocol should allocate the memory buffer for the identity data. 
RAS will free this memory by calling RasEapFreeMemory. 
pdwSizeOfUserDataOut 


Pointer to a DWORD value that, on successful return, contains the size of the data 
pointed to by the ppUserDataOut parameter. 


-. ppwszidentity 


Pointer to a pointer that, on successful return, points to a Unicode string that identifies 
the user requesting authentication. This string will be passed to the authentication 
protocol in the pszidentity member of PPP_EAP_INPUT during the call to 
RasEapBegin. 


_ Return Values 


lf the function succeeds, the return value is NO_ERROR. 


If the function was not able to allocate memory for the user data, the return value should 
be ERROR_NOT_ENOUGH_MEMORY. 


lf the function is called with the RAS_EAP_FLAG_NON_INTERACTIVE flag, but must 
invoke a user interface to determine the user's identity, the function should return 
ERROR_INTERACTIVE_MODE. 
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If the function fails in some other way, the return value should be an appropriate error 
code from Winerror.h, Raserror.h, or MPIOHOF: h. 


Remarks 

The DLL that implements RasEapGetldentity and RasEapFreeMemory may support 
more than one authentication protocol. The dwEapTypeld parameter specifies for which 
protocol to invoke the identity user interface. 


The authentication protocol receives the data returned from RasEapGetldentity in the 
pUserData member of PPP_EAP_INPUT during RasEapBegin. To store the data for 
this user in the registry, the authentication protocol should set the pUserData member of 
PPP_EAP_OUTPUT to point to the data, and the fSaveUserData member of 
PPP_EAP_OUTPUT to TRUE. 


This function is called by the RAS function, ad a 


lf RasEapGetidentity displays a user interface, the user interface must support 
WM_COMMAND messages where LOWORD(wParam) equals IDCANCEL. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Functions, Obtaining Identity 
Information, RasEapFreeMemory, RasEapMakeMessage, intelli cag calla 
PPP_EAP_INPUT 


RasEapGetinfo 


The Connection Manager calls RasEapGetinfo to obtain a set of function pointers fora 
specified authentication protocol. | 


Parameters 


dwEapTypeld — 
| Species the authentication protocol for which to obtain information. 
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pEapInfo | 
Pointer to a PPP_EAP_INFO structure. The structure contains members that RAS 
sets to identify the structure version and the authentication protocol for which function 
pointers are requested. For more information, see PPP_EAP_INFO. 


Return Values 
If the function succeeds, the return value is NO_.ERROR. 


If the function fails, the return value should be an appropriate error code from Winerror.h, 
Raserror.h, or Mprerror.h. 


Remarks 


The DLL that implements RasEapGetInfo may support more than one authentication 
protocol. The dwEapTypeld parameter specifies for which authentication protocol to 
obtain information. 


Implementations of EAP must export the RasEapGetinfo function, since RAS uses 
RasEapGetinfo to obtain pointers to the other authentication protocol functions. 


Upon initialization, the Connection Manager calls RasEapGetinfo for each EAP DLL 
installed in the registry subkey, as explained in the EAP Overview. 


lf the function returns any value other than NO_ERROR, RAS considers the 
authentication protocol to be non-functional. RAS posts an error to the Microsoft® 
Windows NT®/Windows® 2000 Event Log indicating that this protocol did not start 
correctly and therefore is not available. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Functions, EAP (Extensible 
Authentication Protocol) Overview, PPP_EAP_INFO 


RasEaplnitialize 


The RAS Connection Manager calls the RasEaplnitialize function to initialize or 
deinitialize the authentication protocol. 7 
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Parameters 


finitialize 
Specifies whether the authentication protocol should initialize or deinitialize. This 
parameter is TRUE if the protocol should initialize and FALSE if the ee should 
deinitialize. 


Return Values | 
If the function succeeds, the return value is NO_ERROR. 


If the function fails, the return value should be an appropriate error code from Winerror.h, 
Raserror.h, or Mprerror.h. 


Remarks 


The RasEaplnitialize function is not st part of the RRAS API; it is mpleménted in the EAP 
DLL. When the Connection Manager calls the RasEapGetinfo function, it receives a 
PPP_EAP_INFO structure for the authentication protocol. This structure contains a 

_ pointer to the RasEaplnitialize function. 


_ The authentication protocol may set the RasEaplnitialize member in PPP_EAP_INFO 
to NULL. A NULL value indicates that the authentication protocol does not require 
initialization or deinitialization. Therefore, RAS need not call this function. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Functions, Ppp EAP _INFO, 
RasEapBegin, RasEapGetinfo 


RasEapInvokeConfigUI 


The Connection Manager calls the RasEapInvokeConfigUII function to display a dialog 
to obtain configuration information from the user. RAS calls RasEapInvokeConfigUI 
when a new phone-book entry is created or an existing phone-book entry is edited, - 
provided that the authentication protocol for the entry provides a ponfiguration user 
interface. | : 


(continued) 
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(continued) 


Parameters 


dwEapTypeld 
Specifies the authentication protocol for which to invoke the configuration UI. 


hwndParent 
Handle to the parent window for the UI dialog. 


dwFlags 
Specifies whether the computer that is dialing in is a router or a RAS client. If the 
computer is a router, this parameter should be set to: | | | 


RAS_EAP_FLAG_ROUTER 
Otherwise, this parameter should be zero. 


pConnectionDatalin 
Pointer to the connection data currently stored in the phone-book entry. If the phone- 
book entry does not contain any data, this parameter is NULL. 


dwSizeOfConnectionDatalIn 
Specifies the size of the connection data currently stored in the phone-book entry. If 
the phone-book entry for this connection does not contain any data, this parameter 
will be zero. 


ppConnectionDataOut 
Pointer to a pointer that, on successful return, points to the new connection data to 
Store in the phone-book entry. None of this data should be specific to the current 
machine; phone-book entries should be portable from machine to machine. 


pdwSizeOfConnectionDataOut | 
Pointer to a DWORD that, on successful return, points to the size of the new 
connection data to store in the phone-book entry. 


Return Values ais | | oe 
If the function succeeds, the return value is NO_LERROR. 


If the function was not able to allocate memory for the configuration data, the return 
value should be ERROR_NOT_ENOUGH_MEMORY. 


lf the function fails in some other way, the return value should be an appropriate error 
code from Winerror.h, Raserror.h, or Mprerror.h. 


Chapter 13 Extensible Authentication Protocol (EAP) 399 


Remarks 


The DLL that implements RasEapInvokeConfigUI and RasEapFreeMemory may 
support more than one authentication protocol. The dwEapTypeld parameter specifies 


for which protocol to invoke the configuration UI. 


RAS stores the connection data returned by RasEapInvokeConfigUI in the phone-book 
entry for the connection on the client computer. | | 7 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Functions, Client-Side Configuration 
User Interface, 


RasEapFreeMemory, Ee 3 | 
RasEapGetldentity, RasEapInvokeinteractiveUI 


~ RasEapinvokelinteractiveUl © 


The RAS Connection Manager calls the RasEapInvokelnteractiveUI function to display 
a dialog to obtain authentication data from the user. nee font 


arameters 


dwEapTypeld : 
Identifies the authentication protocol for which to invoke the interactive Ul. 

hwndParent — | 
Handle to the parent window for the dialog. eos ge 
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pUIContextData 
Pointer to context data for the interactive UI. The authentication protocol provides a 
pointer to this data as a member of the PPP_EAP_OUTPUT structure. The RAS 
Connection Manager receives the PPP_EAP_OUTPUT structure as an output 
parameter from the RasEapMakeMessage function. 


dwSizeofU!ContextData 
Specifies the size of the context data. The authentication protocol provides the size as 
a member of the PPP_EAP_OUTPUT structure. The RAS Connection Manager 
receives the PPP_EAP_OUTPUT structure as an output parameter from the 
RasEapMakeMessage function. 


ppDataFrominteractiveUl : 
Pointer to a pointer variable. On successful return, ‘this pointer veils will point to a 
memory buffer that contains the data obtained by the interactive UI. The interactive Ul 
allocates this memory. RAS passes this data back to the authentication protocol in the 
PPP_EAP_INPUT structure, then RAS frees this memory by calling 
RasEapFreeMemory. 


If the interactive Ul does not obtain any user-specific data, the pointer that 
ppUserData points to should be set to NULL. 


pdwSizeOfDataFrominteractiveUl 
Pointer to a DWORD variable to receive the size of the data returned from the 
interactive UI. If the interactive UI does not obtain any user-specific data, the DWORD 
variable should be set to zero. 


Return Values 

If the function succeeds, the return value is NO_ERROR. Check the 
ppDataFrominteractiveUI and lpdwSizeOfDataFrominteractiveU! parameters to 
determine if the function returned data from the interactive UI. 


lf the function was not able to allocate memory for the data, the return value should be 
ERROR_NOT_ENOUGH_MEMORY. 


If the function fails in some other way, the return value should be an appropriate error 
code from Winerror.h, Raserror.h, or Mprerror.h. 


Remarks 

The DLL that implements the RasEapInvokelnteractiveUI and RasEapFreeMemory 
functions may support more than one authentication protocol. The dwEapTypeld 
parameter specifies the authentication protocol for which to invoke the interactive UI. 


A pointer to the data returned from the interactive UI is passed back to the authentication 
protocol in the pDataFrominteractiveUI member of PPP_EAP_INPUT structure. The 
PPP_EAP_INPUT structure is ate as a parameter to the RasEapMakeMessage 
function. 


The interactive user interface must support WM eons messages where 
LOWORD(wParam) equals IDCANCEL. 
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Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


| Extensible Authentication Protocol Reference, EAP Functions, Interactive User Interface, 
RasEapFreeMemory, RasEapinvokeConfigUI, RasEapGetidentity, 
RasEapMakeMessage, PPP_EAP_INPUT, PPP_EAP_OUTPUT 


RasEapMakeMessage 


The RasEapMakeMessage function is the framework within which incoming and 
outgoing EAP packets, time outs, and other events such as authentication completion 
are processed for an EAP. RAS calls the ask epMorenes sage oe every time 
there is an incoming or outgoing packet. | 


Parameters 


pWorkBuf 
Pointer to the work buffer. The authentication protocol provides RAS with a pointer to 
this buffer via the RasEapBegin function. : 7 

pReceivePacket 
Pointer to a PPP_EAP_PACKET structure that contains a received packet. A 
pPReceivePacket value of NULL indicates either that RAS is initiating the dialog with 
the authentication protocol, or that a time out has occurred and the authentication 


protocol should resend the last packet. The authentication protocol must determine, 
based on context, which of these two cases is true. 
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pSendPacket | 7 
Pointer to a PPP_EAP_ PACKET structure. The authentication protocol can use this 
structure to specify a packet to send. 

cbSendPacket 
Specifies the size, in bytes, of the buffer scinted to by pSendPacket. 

pEapOutput 

— Pointer to PPP_EAP_OUTPUT structure. 

pEapInput 
Pointer to a PPP_EAP_ INPUT structure. This parameter may be NULL. © 


Return Values 
If the function succeeds, the return value is NO_ERROR. 


If the function fails, the return value should be an appropriate error code from Winerror.h, 
Raserror.h, or Mprerror.h. Any error except for ERROR_PPP_INVALID_PACKET, 
terminates the authentication session. For more information on the 
ERROR_PPP_INVALID_PACKET return code, see EAP Implementation Details. 


Remarks 


The RasEapMakeMessage function is not part of the RRAS API; it is piece in 
the EAP DLL. When the Connection Manager calls the RasEapGetinfo function, it 
receives a PPP_EAP_INFO structure for the authentication protocol. This structure 
contains a pointer to the RasEapMakeMessage function. 


RAS allocates the buffers pointed to by pReceivePacket, pSendPacket, pEapOutput, 
and pEap/Input. The authentication protocol does not allocate any of these buffers. 


Windows NT/2000: Requires Windows 2000. 


- Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Functions, RasEapGetinfo, 
PPP_EAP_INFO, PPP_EAP_INPUT, PPP_EAP_OUTPUT, PPP_EAP_PACKET 


EAP Structures 


Vendors should use the following structure types for authentication Brotocols and 
authentication providers. 


Chapter 13 Extensible Authentication Protocol (EAP) 403 


PPP_EAP_INFO 
PPP_EAP_INPUT 
PPP_EAP_OUTPUT 
PPP_EAP_ PACKET 
RAS _AUTH_ATTRIBUTE 


PPP_EAP_INFO 


The PPP_EAP_INFO structure provides the Connection Manager with information about 
the authentication protocol, including pointers to functions located in the EAP DLL. 


Members| 

dwSizelnBytes a , | 
Specifies the size of the PPP_EAP_INFO structure. RAS passes this value to the 
EAP DLL. The DLL uses this value to determine which version of the 
PPP_EAP_INFO structure RAS is using. 
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dwEapTypeld | 
Specifies a particular authentication protocol. This identifier must be unique 
throughout industry-wide implementation of EAP (see /ETF Internet Draft 1310). The 
implementer of an authentication protocol must obtain this identifier from the Internet 
Assigned Numbers Authority (LANA). 


( * RasEaplnitialize ) 
Pointer to the RasEapInitialize function for the authentication protocol. The 
authentication protocol sets the value of this member. The authentication protocol 
may set this member to NULL, in which case the protocol does not require RAS to call 
this function. 

(* RasEapBegin ) | 
Pointer to the RasEapBegin function for the requested authentication protocol. The 
authentication protocol sets the value of this member. This member may be NULL, in 
which case, the authentication protocol does not require any initialization. If this 
member is NULL, RAS ignores the RasEapEnd member. 

(* RasEapEnd ) 
Pointer to the RasEapEnd function for the authentication protocol. The authentication 
protocol sets the value of this member. 

(* RasEapMakeMessage ) 
Pointer to the RasEapMakeMessage for the requested authentication protocol. The 
authentication protocol sets the value of this member. 


Remarks 


A given EAP DLL may implement more than one authentication protocol. Use the 
dwEapTypeld member to specify for which protocol to retrieve information. © 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Structures, RasEapBegin, 
RasEapEnd, RasEapGetinfo, RasEapMakeMessage. 


PPP_EAP_INPUT 


The PPP_EAP_INPUT structure is used in the interaction between the RAS Connection 
Manager Service PPP implementation and the EAP to provide user information, and to 
facilitate the use of authentication providers such as Windows 2000 domain 
authentication or RADIUS. 
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Members 
dwSizelnBytes 


Specifies the size in bytes of the PPP_EAP_INPUT structure. The value of this 
member can be used to distinguish between current and future versions of this 


structure. 
fFlags 


Specifies zero or more of the following flags that qualify the authentication process. 


Flag 
RAS_EAP_ FLAG ROUTER 


RAS_EAP_FLAG_NON_INTERACTIVE 


RAS_EAP_FLAG_LOGON 


RAS_EAP_FLAG_FIRST_LINK 


fAuthenticator 


Description 


Specifies whether the computer dialing 


in is a router or a RAS client. If the 


computer is a router, this parameter 
should be set. 


Specifies that the authentication 
protocol should not bring up a user- 
interface. If the authentication protocol 
is not able to determine the identity 
from the data supplied, it should return 
anerror, 


Specifies that the user data from 
obtained from Winlogon. 


Indicates that this connection is the 


first link in a multilink connection. See 


Multilink and Callback Connections for 
more information. 


Specifies whether the authentication protocol is operating on the server or client. A 
value of TRUE indicates that the authentication protocol is operating on the server as 
the authenticator. A value of FALSE indicates that the authentication protocol is 
operating on the client as the as the process to be authenticated. 


pwszidentity 


Pointer to an Unicode that identifies the user requesting authentication. This string is 


of the form domain\user or machine\user. 


If the authentication protocol is able to derive the user’s identity from an additional 
source, for example a certificate, it should verify that the identity SO derived matched 


the value of pszidentity. 


| pwszPassword 


Pointer to a Unicode string that contains the user’s account password. Available ony 
if fAuthenticator is FALSE. This member may bet NULL. 


binitialld 


Specifies the identifier of the initial EAP packet sent by the DLL. This value i is 
_ incremented by one for each subsequent request packet. 
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pUserAttributes 
Pointer to an array of RAS_AUTH_ATTRIBUTE structures. The array is terminated 
by a structure with an raaType member that has a value of raatMinimum (see 
RAS_AUTH_ATTRIBUTE_TYPE) During the RasEapBegin call, this array contains 
attributes that describe the currently dialed-in user. When the 
fAuthenticationComplete member is TRUE, this array may contain attributes 
returned by the authentication provider. 


fAuthenticationComplete | | 
Specifies a Boolean value indicating whether the authentication srovider has 
authenticated the user. A value of TRUE indicates authentication completion. Check 
the dwAuthResultCode field to determine if the authentication was successful. Ignore 
this field if the authentication protocol is not using an authentication provider. 


—dwAuthResultCode 
Specifies the result of the authentication provider's authentication process. Successful 
authentication results in NO_ERROR. Authentication failure codes for 

- dwAuthResultCode must come only from Winerror.h, Raserror.h or Mprerror.h. 
Ignore this field if the authentication protocol is not using an authentication provider. 


hTokenimpersonateUser 
Handle to an impersonation token for the user requesting authentication. This 
member is valid only on the client side. For more information on impersonation 
tokens, see Access Tokens. 


fSuccessPacketReceived 
RAS sets this member to TRUE if the client receives an Network Control Protocol 
(NCP) packet even though the client has not yet received an EAP success packet. 
The EAP success packet is a non-acknowledged packet. Therefore, it may be lost 
and not resent by the server. In this situation, the receipt of an NCP packet indicates 
that authentication must have been successful, since the server has moved on to the 
NCP phase of PPP. This member should be examined only on the client side. 


fDataReceivedFrominteractiveUl 
RAS sets this member to TRUE whenever the user exits from the authentication 
protocol’s interactive user interface. 


pDataFrominteractiveUI 
Pointer to data received from the authentication protocol’s interactive user interface. 
This pointer is non-NULL if the fDataReceivedFromInteractiveUI member is TRUE 
and the interactive user interface did, in fact, return data. Otherwise, this pointer 
is NULL. a 


If non- -NULL, the authentication protocol should make a copy of the data i in its own 
~ memory space. RAS frees the memory occupied by this data on return from the call in 
which the PPP_EAP_INPUT structure was passed. To free the MOLY, RAS calls 
the RasEapFreeMemory function. | 
dwSizeOfDataFrominteractiveUI 
Specifies the size, in bytes, of the data pointed to By »DataFrominteractiveUl. If no 
data is returned from the interactive user interface, this member is zero. 
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pConnectionData 
Pointer to connection data received from the authentication protocol’s configuration 
user interface. This data is available only when the PPP_EAP_INPUT structure is 
passed in RasEapBegin. It is not available in calls to RasEapMakeMessage. 


The authentication protocol should make a copy of this data in its own memory space. 
RAS frees the memory occupied by this data on return from the call in which the 
PPP_EAP_INPUT structure was passed. To free the memory, RAS calls the 
RasEapFreeMemory function. 


If the authentication protocol’s configuration user interface does not return any data, 
this member is NULL. 


dwSizeOfConnectionData 
Specifies the size in bytes of the data pointed to by pConnectionData. If 
pConnectionData.is NULL, this member is zero. 


pUserData 
Pointer to user data received from the authentication protocol’s RasEapGetldentity 
function on the client computer. If the authentication protocol does not implement 
RasEapGetldentity, this member points to data from the registry for this user. 


This data is available only when the PPP_EAP_INPUT structure is passed in 
RasEapBegin. It is not available in calls to RasEapMakeMessage. 


The authentication protocol should make a copy of this data in its own memory space. 
RAS frees the memory occupied by this data on return from the call in which the 
PPP_EAP_INPUT structure was passed. 


_ If the RasEapGetldentity function is not implemented or did not return any data, and 
no data exists for the user in the registry, this member is NULL. 


dwSizeOfUserData 
Specifies the size, in bytes, of the data pointed to by pUserData. lf pUserData is 
NULL, this member is zero. 


hReserved 
This member is reserved. 


Remarks 


The PPP_EAP_INPUT structure is passed by RAS to the authentication protocol in calls 
to RasEapBegin and RasEapMakeMessage. 


The pszidentity and pszPassword members of the PPP_EAP_INPUT structure are 
used by the RasEapBegin function to obtain user information. The pszPassword 
member is non-NULL only if the fAuthenticator member is FALSE, that is, the 
authentication protocol is running on the client computer. 


lf the authentication protocol is using an authentication provider, such as Radius or 
Windows 2000 domain authentication, the following members are used to interface with 
the authentication provider: 
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(continued) 


Members 


Action 
Specifies a PPP_EAP_ACTION value. The Connection Manager carries out this 


action on behalf of the authentication protocol. 


dwAuthResultCode 
Specifies whether authentication was successful. Any non-zero value for 


dwAuthResultCode indicates failure. The failure code must come from Winerror.h, 
-Raserror.h or Mprerror.h. This member is valid only if the Action member has a value 
of EAPACTION_Done or EAPACTION_SendAndDone. - 


pUserAttributes 
Pointer to an optional array of RAS_AUTH_ATTRIBUTE structures. The array is 


terminated by a structure with an raaType member that has a value of raatMinimum — 
see RAS_AUTH_ATTRIBUTE_TYPE). | 


This member should be set on the authenticator side when Action is 
EAPACTION_Authenticate, or when Action is EAPACTION_Done or 
EAPACTION_SendAndDone. and dwAuthResultCode is zero. 


When Action is EAPACTION_ Authenticate, the array may contain additional 
attributes necessary to authenticate the user, e.g. the user-password. If the 
authentication protocol passes in only the user name, RAS does not invoke the 
authentication provider to authenticate the user, Instead, RAS just passes back the 


current attributes for the user. 


When Action is EAPACTION_Done or EAPACTION_SendAndDone, and 
dwAuthResultCode is zero, the array may contain additional attributes to assign to 
the user. These attributes overwrite any attributes of the same type returned by the 


authentication provider. 
The authentication protocol should free this memory in its RasEapEnd function. 


finvokelnteractiveUl 
‘Specifies whether RAS should invoke the authentication protocol’s interactive UI. If 
the authentication protocol sets this member to TRUE, RAS invokes the interactive Ul, 
by calling the RasEapInvokelinteractiveUI function provided by the authentication 
protocol. | : | 
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pUIContextData | 

~ Pointer to context data that RAS should pass in the call to 
RasEapInvokeinteractiveUl. The authentication protocol should free this memory in 
its implementation of RasEapEnd. | 


dwSizeOfuiContextData 
Specifies the size of the context data that RAS should pass in the call to 
RasEapIinvokeinteractiveuUl. 


fSaveConnectionData 
Specifies whether RAS should save the information pointed to by the — 
pConnectionData member. If fSaveConnectionData is TRUE, RAS will save the 
data in the phone book. This is only valid for the process that is being authenticated. 


pConnectionData 
Specifies data specific to the connection, that is, data that is not specific to any 
particular user. If the fSaveConnectionData member is TRUE, RAS saves the 
connection data in the phone book. The authentication protocol should free the 
memory occupied by this data during the call to RasEapEnd. 


dwSizeOfConnectionData; 
Specifies the size, in bytes, of the data pointes: to by the Pe ee ae, member. 


fSaveUserData 
Specifies whether RAS should save the user data pointed to by the pUserData 
member. If this parameter is TRUE, RAS saves the user- specific data in the registry 
under HKEY_ CURRENT_ USER. | 


pUserData | 7 
Pointer to user data that RAS should save in the registry. RAS : saves 5 this data j inthe — 
registry under HKEY_CURRENT_USER. The authentication protocol should free this 
memory during the call to RasEapEnd. 


dwSizeofUserData 
Specifies the size in bytes of the data oaless to by pUserData. 


Remarks 


Use the RasEapMakeMessage function to pass the PPP_EAP_OUTPUT structure 
between the authentication protocol and the Connection Manager 


The authentication protocol may use the PPP_EAP_OUTPUT structure to return the 
Microsoft Point to Point Encryption (MPPE) session key. The authentication protocol 
should place the session key in the value field of a sub-attribute contained within the 
value field of an attribute of type raatVendorSpecific (see 
RAS_AUTH_ATTRIBUTE_TYPE). The sub-attribute should have a Vendor-ID of 311 
(Microsoft) and a Vendor-Type of 12 (MS-CHAP-MPPE-Keys). The authentication 
protocol should set the pUserAttributes member to point to the raatVendorSpecific 
attribute, and set the Action member to EAPACTION_Done or | 
EAPACTION_SendAndDone. For more information about the format of the MPPE sub- 
attribute see htto://search.ietf.org/internet-drafts/dratt-ietf-radius-mschap-attr-01.txt. - 
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For more information about attribute formats see RAS AUTH A TTRIBUTE, 
RAS_AUTH_ATTRIBUTE_TYPE, and 


http://src.doc.ic.ac.uk/computing/internet/ric/rfc2 138. txt. 


Beast 


es S 


| Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Structures, 


RAS_AUTH_ATTRIBUTE, PPP_EAP_ACTION, RasEapInvokelinteractiveUl, © 
_RasEapMakeMessage 


PPP_EAP_PACKET 


The PPP_EAP_PACKET structure specifies information about a packet being processed 
by the authentication protocol. 


Members 
Code 


Specifies the type of packet that is being sent or received by the authentication 
protocol. This parameter can be one of the four following values. 


Value Meaning 
EAPCODE_Request The packet is a request. 
EAPCODE_Response The packet is a response. 
EAPCODE_Success The packet indicates success. 
EAPCODE_Failure The packet indicates failure. 


Id 
Specifies the identifier of the packet. The authentication protocol is responsible for 
maintaining packet counts for sessions, as that packet count pertains to EAP activity. 
Length[2] | 
Specifies the length of the packet. 
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Data[1] 
Specifies the data transmitted by this packet. If the packet is a request or a response 
packet, the first byte of this member signifies its type. For more information about 
packet types and requirements for type reservation, refer to the PPP EAP Internet 
draft, found at http://ds2.internic.net/internet-drafts/draft-ietf-pppext-eap-auth-02. txt. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Structures, RasEapGetinfo, 
RasEapMakeMessage, PPP_EAP_INFO, PPP_EAP_INPUT, PPP_EAP_OUTPUT 


RAS_AUTH_ATTRIBUTE 


The RAS_AUTH_ATTRIBUTE structure is used to pass authentication attributes, of type 
RAS_AUTH_ATTRIBUTE_TYPE, during an EAP session. 


Members 

raaType | 7 oe oth 
Specifies the type of attribute, as defined in the RAS_AUTH_ATTRIBUTE_TYPE 
enumerated type. | 


dwLength a 
Specifies the length in bytes of the value of this attribute. If the Value member is a 
pointer, dwLength specifies the length of the buffer pointed to. If the Value member 
is the value itself, dwLength specifies how much of the length of the Value member 
is taken up by the value. | 


Value | | 
Specifies the value of the attribute. Although this member is of the PVOID type, this 
member sometimes contains the value of the attribute rather than pointing to the 
value. The only way to know whether to interpret the Value member as a pointer to 
the value or the value itself, is to check the raaType member. See the reference page 
for RAS_AUTH_ATTRIBUTE_TYPE for information about how the Value member 
should be interpreted for different types. 
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Remarks 


Often an array of these structures is used to store or obtain a set of attributes for a given 
user. Since the number of attributes for a session is unknown, the array must be 
dynamic. The array is terminated by a structure with an raaType member that has a 


value of raatVinimum 


| Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Structures, 
RAS AUTH_ATTRIBUTE_TYPE 


EAP Enumerated Types | | 


Use the following enumerated types for authentication protocols and authentication 
providers: | | 
PPP_EAP_ACTION 
| RAS_AUTH_ATTRIBUTE_TYPE | 


PPP_EAP_ACTION Sf te 


The PPP_EAP_ACTION enumerated type specifies actions that the Connection 
anager should take on behalf of the authentication protocol. 


oe 
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Values 

EAPACTION_NoAction 
Directs the Connection Manager to be passive. 

EAPACTION_Done 

_ Directs the Connection Manager Service to end the authentication session. 
EAPACTION_Done indicates that the dwAuthResultCode member of the 
PPP_EAP_OUTPUT structure is set with an appropriate value. 

EAPACTION_SendAndDone 
Directs the Connection Manager to senda message (without a time out), then end the 
authentication session. EAPACTION_SendAndDone indicates that the 
dwAuthResultCode member of the PPP_EAP_OUTPUT structure is set with an 
appropriate value. 

EAPACTION_Send : 
Directs the Connection Manager to send a message without setting a time out to wait 
for a reply. 

EAPACTION_SendWithTimeout 
Directs the Connection Manager to send a message and set a time out to wait fora 
reply. 

EAPACTION_SendWithTimeoutinteractive 
Directs the Connection Manager to send a message an set a time out to wait fora 
reply, but instructs the Connection Manager not Elo increment the retry counter. 

EAPACTION_Authenticate | 
Directs the Connection Manager to invoke the authentication provider to authenticate 

_ the user. On 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP enumetalies Types, 
-PPP_ EAP_INPUT, PPP_EAP_OUTPUT 


RAS. _AUTH ATTRIBUTE _TYPE 


The RAS _ AUTH _ATTRIBUTE _TYPE anumerated type specifies attribute values used 
for session authentication. Further details for values in this enumerated type may be 
obtained by referring to one of the three following references: RFC 2138, REC 2139, or 
draft-ietf-radius- ext-04. ‘ 
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raatNASIPAddress 
Specifies the Network Access Server (NAS) IP address. An Access-Request should 
specify either an NAS IP address or an NAS identifier. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more information, 
see RFC 2138. 


raatNASPort 
Specifies the physical or virtual private network (VPN) through which the user is 
connecting to the NAS. Note that this value is not a port number in the sense of TCP 
or UDP. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral 
_ value. For more information, see RFC 2138. 


raatServiceType 
Specifies the type of service the user has requested or the type of service to be 
provided. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral 
value. For more information, see RFC 2138. 


raatFramedProtocol 
Specifies the type of framed protocol to use for framed access, for example SLIP, 
PPP, or ARAP (AppleTalk Remote Access Protocol). The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more information, | 
see RFC 2138. | 


raatFramedlPAddress 
Specifies the IP address to be configured for the user requesting authentication. This 
attribute is typically returned by the authentication provider. However, the NAS may 
use it in an authentication request to specify a preferred IP address. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32- bit integral value. For more information, 
see RFC 2138. 


_raatFramediPNetmask 
Specifies the IP network mask for a user that is a router to a network. The value field 
_ in RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more 
information, see RFC 2138. 


raatFramedRouting 3 
Specifies the routing method for a user that is a router to a network. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more information, 
see RFC 2138. | 


raatFilterld 
Specifies the filter list for the user requesting authentication. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see | 
RFC 2138. 
raatFramedMTU 
Specifies the Maximum Transmission Unit (MTU) for the user. This attribute is used i in 
cases where the MTU is not negotiated through some other means, such as PPP. 
The value field in RAS_-AUTH_ATTRIBUTE for this type is a 32-bit pteaie value. For 
more information, see RFC 2138. 
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raatFramedCompression 
Specifies a compression protocol to use for the connection. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more information, 
see RFC 2138. 


raatLoginIPHost 
Specifies the system with which to connect the user. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more information, 
see RFC 2138. 


raatLoginService 
Specifies the service to use to connect the user to the host eostiied by 
raatLoginIPHost. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32-bit 
integral value. For more information, see RFC 2138. 


raatLoginTCPPort 
Specifies the port to which to connect the user. This attribute is present only if the 
raatLoginService attribute is present. The value field in RAS_AUTH_ATTRIBUTE for 
this type is a 32-bit integral value. For more information, see RFC 2138. 


raatUnassigned1 
This value is currently unassigned. 


raatReplyMessage 
Specifies a message to display to the user. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see 
RFC 2138. 


raatCallbackNumber 
Specifies a callback number. The value field in RAS_AUTH_ATTRIBUTE for this type — 
is a pointer. For more information, see RFC 2138. : 


raatCallbackld 
Specifies a location to call back. The value of this attribute is interpreted by the NAS. 
The value field in RAS_AUTH ATTRIBUTE for this type is a pointer. For more 
information, see RFC 2138. 


raatUnassigned2 
This value is currently unassigned. The value field in RAS _AUTH_ATTRIBUTE for 
this type is also undefined. 


_ raatFramedRoute 
Specifies routing information to configure on the NAS for the user. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see 
RFC 2138. 


raatFramedlPXNetwork : 
Specifies the IPX network number to configure for the user. The value field in 
RAS AUTH_ATTRIBUTE for this ied is a 32-bit integral value. For more information, 
see RFC 21 38. 


raatState 
Refer to RFC 2138 for detailed information about this value. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. 
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raatClass | 
Specifies a value that is provided to the NAS by the authentication provider. The NAS 
should use this value when communicating with the accounting provider. The value 
field in RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see 
RFC 2138. 


raatVendorSpecitic 
Specifies a field for extended attributes. The value field in RAS_AUTH_ATTRIBUTE 
for this type is a pointer. For more information, see RFC 2138. _ 


raatSessionTimeout 
Specifies the maximum number of seconds for which to provide service to the user. 
After this time, the session is terminated. The value field in RAS_AUTH_ATTRIBUTE 
for this type is a 32-bit integral value. For more information, see RFC 2138. 


raatldle Timeout 
Specifies the maximum number of consecutive seconds the session can be idle. If the 
idle time exceeds this value, the session is terminated. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more information, 
see RFC 2138. 


raatTerminationAction 
Refer to the above-referenced files at ds.internic.net for detailed information about this 
value. The value field in RAS_AUTH_ATTRIBUTE for this type is 32-bit integral 
value. For more information, see RFC 2138. 


raatCalledStationld 
Specifies the number that the user dialed to connect to the NAS. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see 
RFC 2138. — 


raatCallingStationld 
Specifies the number from which the user is calling. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see 
RFC 2138. 


raatNA Sldentifier | 
Specifies the NAS identifier. An Access-Request should specify either an NAS 
identifier or an NAS IP address. The value field in RAS_AUTH_ATTRIBUTE for this 
type is a pointer. For more information, see RFC 2138. 


raatProxyState 
Specifies a value that a proxy server includes when forwarding an authentication 
request. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. For 
more information, see RFC 2138. 

raatLoginLAT Service 
Specifies an attribute that is not currently used for authentication on Windows 2000. 
For more information, see RFC 2138. | 

raatLoginLA TNode 
Specifies an attribute that is not currently used for authentication on Windows 2000. 
oF more information, see RFC 2138. 
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raatLoginLATGroup 
Specifies an attribute that is not currently used for authentication on Windows 2000. 
For more information, see RFC 2138. 


raatFramedApple TalkLink 
Specifies the AppleTalk network number for the user when the user is another router. 
The value field in RAS_AUTH_ATTRIBUTE for this type is 32-bit integral value. For 
more information, see RFC 2138. 


raatFramedApple TalkNetwork 
_ Specifies the AppleTalk network number that the NAS should use to allocate an 
AppleTalk node for the user. This attribute is used only when the user is not another 
router. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral 
value. For more information, see RFC 2138. 


raatFramedApple TalkZone 
Specifies the AppleTalk default zone for the user. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see 
RFC 2138. 


raatAcctStatus Type 
Specifies whether the accounting provider should start or stop accounting for the user. 
The value field in RAS_-AUTH_ATTRIBUTE for this type is a 32-bit integral value. For 
more information, see RFC 2139. 


raatAcctDelayType 
Specifies the length of time that the client has been attempting to send the current 
request. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral 
value. For more information, see RFC 2139. 


raatAcctinputOctets 
Specifies the number of octets that have been received during the current accounting 
session. The value field in RAS_AUTH_ATTRIBUTE is this type is a 32-bit Integral 
value. For more information, see RFC 2139. 


raatAcctOutputOctets 
Specifies the number of octets that were sent during the current accounting session. 
The value field in RAS_-AUTH_ATTRIBUTE for this type is a 32-bit integral value. For 
more information, see RFC 21339. 


raatAcctSessionld 
Specifies a value to enable the identification of matching start and stop records within 
a log file. The start and stop records are sent in the raatAcctStatusType attribute. The © 
value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. For more 
information, see RFC 2139. | 


raatAcctAuthentic 
Specifies, to the accounting provider, how the user was authenticated; for example by 
Windows 2000 Directory Services, RADIUS, or some other authentication provider. 
The value field in RAS_AUTH_ATTRIBUTEfor this type is a 32- bit integral value: For 
more information, see RFC 2139. 
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_raatAcctSessionTime 

Specifies the number of seconds that have elapsed in the current accounting session. 
The value field in RAS_AUTH_ATTRIBUTE for this type is a 32- bit integral value. For 
more information, see RFC 2139. 


raatAcctInputPackets | | 
Specifies the number of packets that have been received during the current 
accounting session. The value field in RAS_AUTH_ATTRIBUTE for this type is a 
32-bit integral value. For more information, see RFC 2139. | 


raatAcctOutputPackets 
Specifies the number of packets that have been sent during the current accounting 
session. The value field in RAS_-AUTH_ATTRIBUTE for this type is a 32-bit integral 
value. For more information, see RFC 2139. 


raatAcctTerminateCause 
Specifies how the current accounting session was terminated. The value field in — 
RAS_AUTH_ATTRIBUTE for this type is a 32- bit integral value. For more information, 
see RFC 2139. | 


raatAcctMultiSessionld 
Specifies a value to enable the identification of related accounting sessions within a 
log file. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral 
value. For more information, see RFC 2139. 


raatAcctLinkCount | 
Specifies the number of links if the current accounting session is using a multilink 
connection. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32-bit. 
integral value. For more information, see RFC 2139. 


raatAcctEventTimeStamp 
Specifies an attribute that is included in an accounting request packet. It specifies the 
time that the event took place. The value field in RAS_AUTH_ATTRIBUTE for this 
_type is a 32-bit integral value. For more information, see the Radius Extensions 04 
internet draft. 


raatMD5CHAPChallenge 
Specifies the CHAP challenge sent by the NAS to a CHAP user. The value field in 
RAS_AUTH _ATTRIBUTE for this type is a pointer. For more information, see 
RFC 2138. 


raatNASPortType 
Specifies the type of the port through which the user is connecting, for example, | 
asynchronous, ISDN, virtual. The value field in RAS_AUTH_ATTRIBUTE for this type 
is a 32-bit integral value. For more information, see RFC 2138. | 

raatPortLimit 
Specifies the number of ports the NAS should make available to the user for multilink 
sessions. The value field in RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral 
value. For more information, see RFC 2138. 
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raatLoginLATPort 

_ Specifies an attribute that is not currently used for authentication on Windows 2000. 
Please refer to the above-referenced files at ds.internic.net for detailed information 
about this value. 


raatARAPPassword 
Specifies a password to use for AppleTalk Remote feces Protocol (ARAP) 
authentication. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. 
For more information, see the Internet draft, draft-ietf-radius-ext-04. 


raatARAPFeatures 
Specifies information that an NAS should send back to the user in an ARAP “feature 
flags” packet. The value field in RAS_AUTH_ATTRIBUTE for this type is a pointer. 
For more information, see the Internet draft, draft-ietf-radius-ext-04. 


raatARAPZoneAccess — 
Specifies how to use the ARAP zone list for the user. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more information, 
see the Internet draft, draft-ietf-radius-ext-04. 


raatARAPSecurity 
Specifies an ARAP security module to use during a secondary authentication phase 
between the NAS and the user. The value field in RAS_AUTH_ATTRIBUTE for this 
type is a 32-bit integral. For more information, see the Internet draft, 
draft-ietf-radius-ext-04. 


raatARAPSecurityData 
Specifies the data to use with an ARAP security module. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see the 
Internet draft, draft-ietf-radius-ext-04. 


raatPasswordRetry 
Specifies the number of password retry attempts to permit the user. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. 


raatPrompt 
Specifies whether the NAS should echo the user response to a challenge. The value 
field in RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more 
information, see the Internet draft, draft-ietf-radius-ext-04. 


raatConnectintfo 
Specifies information about the type of connection the user is using. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a Pointer. For more information, see the 
Internet draft, draft-ietf-radius-ext-04. 

raatConfigurationToken 
Specifies user-profile information in communications between RADIUS Proxy Servers 
and RADIUS Proxy Clients. The value field in RAS_AUTH_ATTRIBUTE for this type 
is a pointer. For more information, see the Internet draft, draft-ietf-radius-ext-04. 
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raatEAPMessage 
Specifies that EAP information be sent directly between the user and the 
authentication provider. The value field in RAS_AUTH_ATTRIBUTE for this type is a 
pointer. For more information, see the Internet draft, draft-ietf-radius-ext-04. 


raatSignature 
Specifies a signature to include with CHAP, EAP, or ARAP packets. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see the 
Internet draft, draft-ietf-radius- ext-04. 


raatAcctIinteriminterval 
Specifies the time, in seconds, between accounting updates. The value field in. 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more information, 
see the Internet draft, draft-ietf-radius-ext-04. 


raatARAPChallenge 
_ Specifies a Apple Remote Access Protocol (ARAP) challenge. In ARAP, both the 
server and the client may issue challenges. The value field in 7 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see the 
Internet draft, draft-ietf-radius-ext-04. 


raatARAPGuestLogon : | 
Specifies a Apple Remote Access Protocol (ARAP) guest logon. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a 32-bit integral value. For more information, | 
see the Internet draft, draft-ietf-radius- ext-04. 


raatARAPChallengeResponse 
Specifies the response to a Apple Remote Access Protocol (ARAP) challenge. In 
ARAP, either the server or the client may respond to challenges. The value field in 
RAS_AUTH_ATTRIBUTE for this type is a pointer. For more information, see the 
Internet draft, draft-ietf-radius-ext-04. 


raatReserved | 
_ The value field in RAS_AUTH_ATTRIBUTE for this type is undefined. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Raseapif.h. 


Extensible Authentication Protocol Reference, EAP Enumerated Types, 
RAS_AUTH_ATTRIBUTE 


Extensible Authentication Protocol COM Interfaces 


Implement the following COM interfaces when implementing an authentication protocol 
for Microsoft® Windows® 2000 Server: | | 


IEAPProviderConfig 
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When to Implement 


Implement the IEAPProviderConfig interface to provide a configuration UI for an EAP 
provider. This interface is for configuring the EAP provider on the server. For information 
about the client-side configuration, see the reference page for the 
RasEapInvokeConfigUI function. 


When to Use 


The system calls the methods of this interface when a user chooses to configure an EAP 
provider in the R RAS snap-in. 


Methods in Vtable Order 


lUnknown Methods Description 

Query Interface | Returns pointers to supported interfaces 

AddRef Increments reference count 

Release | Decrements reference count 
~IEAPProviderConfig Methods __ Description 

Initialize | Initializes an EAP configuration session 

Uninitialize Shuts down an EAP configuration session 

ServerlnvokeConfigUI Invokes the EAP configuration user interface 


RouterinvokeConfigUI 
RouterlnvokeCredentialsUl 


SS SS ac 


Windows NT/2000: Requires Windows 2000. - 
Header: Declared in Rrascfg.h. 


Extensible Authentica 
Interfaces 


IEAPProviderConfig::Initialize 


The system calls the IEAPProviderConfig::Initialize method to initialize an EAP 
configuration session with the specified computer. | 
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Parameters 


pszMachineName 
Pointer to a string that contains the name of the computer on which to configure EAP. 


dwEapTypeld 
Specifies the EAP for which to initialize a configuration session. 


puConnectionParam 
Pointer to an unsigned integer variable. On successful return, the value of this 
variable identifies this configuration session. 


Return Values 
If the function succeeds, the return value should be S_OK. 


If the function fails, the return value should be one of the following codes. 


Value Description 

E FAIL | Non-specific error 

E_INVALIDARG ~ One of the arguments is invalid 

E_OUTOFMEMORY The method failed because it was unable to 
allocate required memory 

E UNEXPECTED | An unexpected error occurred 

Remarks 


The configuration UI should allow the user to configure the EAP provider on a remote 
computer. Establish the connection to the remote computer ae the call to 
IEAPProviderConfig::Initialize. 


The DLL that implements IEAPProviderConfig may support more than one 
authentication protocol. The dwEapTypeld parameter specifies for which authentication 
protocol to initialize a configuration session. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Rrascfg.h. 
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Extensible Authentication Protocol Reference, Extensible Authentication Protocol COM 
Interfaces, IEAPProviderConfig, IEAPProviderConfig::RouterInvokeConfigUI, 
lIEAPProviderConfig::RouterInvokeCredentialsUI, 
IEAPProviderConfig::ServerInvokeConfigUI, IEAPProviderConfig::Uninitialize 


IEAPProviderConfig::Uninitialize 


The system calls the IEAPProviderConfig::Uninitialize method to shutdown the 
specified EAP configuration session. 


Parameters 
dwEapTypeld 
_ Specifies the EAP for which to shut down the configuration session. 


uConnectionParam | 
Specifies the configuration session to shut down. 


Return Values 
lf the function succeeds, the return value should be S_OK. 


lf the function fails, the return value should be one of the following codes. © 


Value Description 

E_FAIL | Non-specific error 

E_INVALIDARG One of the arguments is invalid 

E OUTOFMEMORY The method failed because it was unable to 
7 allocate required memory 

E_UNEXPECTED | _ An unexpected error occurred 

Remarks 


The configuration UI should allow the user to configure the EAP provider on a remote 
computer. Delete the connection to the remote computer during the call to 
IEAPProviderConfig::Uninitialize. 


The DLL that implements IEAPProviderConfig may support more than one 
authentication protocol. The dwEapTypeld parameter specifies for which authentication 
protocol to shut down the configuration session. 
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Windows NT/2000: Requires Windows 2000. 
Header: Declared in Rrascfg.h. 


Extensible Authentication Protocol Reference, Extensible Authentication Protocol COM 
Interfaces, IEAPProviderConfig, IEAPProviderConfig::Initialize, 


IEAPProviderConfig::RouterlInvokeConfigUI, 
IEAPProviderConfig::RouterInvokeCredentialsUI, 
IEAPProviderConfig::ServerinvokeConfigUI 


IEAPProviderConfig::ServerlnvokeConfigUI 


The system calls the IEAPProviderConfig::ServerInvokeConfigUI method to invoke 
the configuration user interface for EAP authentication between a remote access client 


and server. 


eS 
sa 


Sas 


Parameters 


-~dwEapTypeld 
Specifies the EAP for which to invoke the configuration user interface. 


uConnectionParam 
Specifies the configuration session for which to invoke the user interface. 


Wnd | 
Handle to the parent window for the configuration user interface. 


wReserved1 
This parameter is reserved and should be zero. 


wReserved2 
This parameter is reserved and should be Zero. 


eturn Values | 
If the function succeeds, the return value should be S_OK. 
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If the function fails, the return value should be one of the following codes. 


Value Description 

E FAIL Non-specific error 

E_INVALIDARG One of the arguments is invalid 

E_OUTOFMEMORY | The method failed because it was unable to 
allocate required memory 

E_UNEXPECTED An unexpected error occurred 

Remarks 


The DLL that implements IEAPProviderConfig may support more than one | 
authentication protocol. The dwEapTypeld parameter specifies for which authentication 
protocol to invoke the configuration user interface. 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Rrascfg.h. 


Extensible Authentication Protocol Reference, Extensible Authentication Protocol COM 
Interfaces, IEAPProviderConfig, IEAPProviderConfig::Initialize, 
IEAPProviderConfig::Uninitialize, IEAPProviderConfig::RouterInvokeConfigUI, 
IEAPProviderConfig::RouterInvokeCredentialsuUI 


IEAPProviderConfig::RouterInvokeConfigUI 


The system calls the IEAPProviderConfig::RouterInvokeConfigUI method to invoke 
the configuration user interface for EAP authentication between two routers: 
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Parameters 
dwEapTypeld 
Specifies the EAP for which to invoke the configuration user interface. 
uConnectionParam 
Specifies the configuration session for which to invoke the user interface. 
hwndParent | 
_- Handle to the parent window for the configuration user interface. 


dwFlags 
Specifies the RAS_ EAP_ FLAG_ROUTER flag. This is the only valid flag for this 
parameter and it indicates that authentication is between two routers. This parameter 
will always include this flag. 
pConnectionDataln 
Pointer to the current configuration data for the interface. 
dwSizeOfConnectionDataln 
Specifies the size of the current configuration data pointed to by the 
pConnectionDataln parameter. 
ppConnectionDataOut 
Pointer to a pointer to a buffer that contains the new configuration data for the 
interface. 
pdwSizeOfConnectionDataOut | 
Pointer to a DWORD variable to receive the size of the new configuration data. 


Return Values | 
__ If the function succeeds, the return value should be S_OK. 


lf the function fails, the return value should be one of the following codes. 


Value | Description 

E FAI Non-specific error 

E_INVALIDARG One of the arguments is invalid 

E_OUTOFMEMORY - The method failed because it was unable to 
| allocate required memory 

E_ UNEXPECTED ; An unexpected error occurred 


Windows NT/2000: Requires Windows 2000. 
Header: Declared | in Rrascfg.h. 
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Extensible Authentication Protocol Reference, Extensible Authentication Protocol COM 
Interfaces, IEAPProviderConfig, IEAPProviderConfig::Initialize, 
IEAPProviderConfig::RouterInvokeCredentialsUI, 
IEAPProviderConfig::ServerInvokeConfigUI, IEAPProviderConfig::Uninitialize 


IEAPProviderConfig::RouterInvokeCredentialsUI 


The system calls the IEAPProviderConfig::RouterInvokeCredentialsUI method to 
invoke the credentials user interface for EAP authentication between two routers. 


Parameters 


dwEapTypeld 
_ Specifies the EAP for which to invoke the configuration user interface. 


uConnectionParam 
pecifies the configuration session for which to invoke the user interface. 


wndParent 
Handle to the parent window for the configuration user interface. 


wFlags 
pecifies the RAS_EAP_FLAG_ROUTER flag. This is the only valid flag for this 
parameter and it indicates that authentication is between two routers. This parameter 
will always include this flag.. 


ConnectionDatalIn 
Pointer to the current configuration data for the interface. 


wSizeOfConnectionDataln 
specifies the size of the current configuration data pointed to by the 
pConnectionDataIn parameter. 


; 
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pUserDatalIn 
Pointer to the current credential data for the interface. 


dwSizeOfUserDataln 
Specifies the size of the current credentials data. 


ppUserDataOut 


Pointer to a pointer to a buffer to receive the new credentials data for the interface. 


pdwSizeOfUserDataOut 
Pointer to a DWORD variable to receive the size of the new credentials data. 


Return Values 
If the function succeeds, the return value should be S_OK. 


If the function fails, the return value should be one of the following codes. © 


Value Description 

E FAIL Non-specific error 

E_INVALIDARG — One of the arguments is invalid 

E OUTOFMEMORY _ The method failed because it was unable to 
: _ allocate the required memory 

E_ UNEXPECTED An unexpected error occurred 


Windows NT/2000: Requires Windows 2000. 
Header: Declared in Rrascfg.h. : 
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Extensible Authentication Protocol Reference, Extensible Authentication Protocol COM 


Interfaces, IEAPProviderConfig, IEAPProviderConfig::Initialize, 
IEAPProviderConfig::RouterInvokeConfigUI, 
IEAPProviderConfig::ServerInvokeConfigUI, IEAPProviderConfig: -Uninitialize 
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CHAPTER 14 


Tracing 


Tracing Overview 
The following documentation describes the implementation of the common tracing DLL, 
which provides a uniform mechanism for generating diagnostic output for the Microsoft® 
Windows NT®/Windows® 2000 Routing and RAS components as well as any other 
application that wishes to use the DLL. The DLL provides dynamic configuration change, 
allowing a user to direct output to a console or to a specified file. In the case of files, the 
user can specify the maximum size for the file. 


Using Tracing 
| Each application or service component calls TraceRegister to obtain an Identifier (ID) to 
use in calls to the output functions. On this call, the DLL reads configuration information 
for the caller from the registry, and sets up the console or file to which output will be 
sent. In addition, a critical section is created that will be used to synchronize calls to the 
tracing DLL functions by the registering component’s threads. An event is associated 
with the registry key for the caller, so that changes to the tracing parameters for the 
caller can be handled dynamically. 


After registering, the application may call the output functions, passing the ID returned by 
TraceRegister. When the application no longer requires the tracing DLL’s support, it 
~ should call TraceDeregister so that handles associated with it can be closed. 


_ There are two versions of each output function. One version prefixes the output it 
generates with standard information such as the name associated with the caller, the 
_ thread ID of the caller, and the current time. The other version allows the caller to omit — 
the standard information normally generated. For instance, TracePrintf includes 
_ Standard information, but TracePrintfEx does not, unless the flag passe’ to it specifies 
~ that it should. 


Support for Unicode clients is built into the tracing DLL. All that is required is that the 
client define the constant UNICODE before including the header containing definitions 
for the tracing: DLL functions. 
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Configuration 


In order to enable console tracing, the value EnableConsoleTracing must exist indar 
the registry key 


HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\TRACING 


and be non-zero. If this value does not exist, or is zero, console tracing is disabled. This 
value is read when rtutils.dll is loaded; changes to this value after rtutils.dll is already 


- loaded will have no effect until the DLL is unloaded and loaded again. 


In addition to the preceding “global” value, the registry may also contain values for 
individual clients. When a client me: calls TraceRegister, the tracing DLL looks under 
the registry key 


HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\TRACING\XYZ 


for the following values: 


e EnableConsoleTracing: this is a REG_DWORD that defaults to zero; tracing to the 
console is enabled if this value is non-zero. 

e EnableFileTracing: this is a REG_DWORD that defaults to zero; tracing to a file 
named XYZ.LOG is enabled if this value is non-zero. 

e ConsoleTracingMask: this is a REG_DWORD that defaults to OxFFFFOOOO; the bits 
in the high-order word correspond to components in the client. If a call to one of the 
extended output functions has the flag TRACE_USE_MASK set, this registry value is | 
compared against the high-order word of the flag passed to the output function, to 
decide whether or not to send the output to the console. 

e FileTracingMask: this is a REG_DWORD that defaults to OxFFFFOOOO; it operates 
similarly to ConsoleTracingMask. 

e MaxFileSize: this is a REG_DWORD that defaults to 0x10000; this is the maximum 
size a tracing file can grow to before itis renamed. __. 

e FileDirectory: this is a REG_EXPAND_SZ that defaults to %WINDIR%\TRACING; 

this Is the directory in which the tracing file is created. 


The defaults are used only if the key is found (or can be created) but some values are 
absent from the key. If the registry key is not found and cannot be created, the call to 
TraceRegister fails. 


Alternatively, a client “xyz” could call TraceRegisterEx, which takes a flag allowing the 
caller to specify the settings to use. Thus, a client could use the tracing DLL without 
creating any key in the registry. For instance: | 


would register the client “xyz” to use the console for tracing, and the tracing DLL would 
not attempt to read the registry key for the client. Similarly. 
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would register the client “abc” to use a file for tracing, bypassing the registry key for the 
client. However, for console tracing, using TraceRegisterEx still requires that the global 
EnableConsoleTracing value exist under 


HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\TRACING _ 


and be non-zero. 


Console Manipulation 


The tracing DLL creates a thread that runs in the background, detecting changes to the 
configuration of clients that use the registry, as well as handling the following key- 
presses in the console: 


Key pressed Action taken 

Control-Tab displays the screen for the next console client 

Control-Shift-Tab displays the screen for the previous console client 

Pause toggles tracing for the displayed console client - 
_Space-bar toggles tracing for the displayed console client 

Up-arrow | moves screen up by one line 

Down-arrow | moves screen down by one line 

Left-arrow moves screen left by one column 

Right-arrow moves screen right by one column 

Page-up moves screen up by one page 

Page-down moves screen down by one page 


Tracing Reference 


Use the following functions to add tracing functionality to your software: 


TraceDeregister | TracePutsEx 
TraceDump TraceRegister 
TraceDumpEx | TraceRegisterEx 
TracePrintf 7 TraceVprintf 


TracePrintfEx TraceVprintfEx 
TracePuts | : 
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TraceDeregister 


The TraceDeregister function frees resources and closes files associated with tracing 
registration on behalf the calling service or application. Call TraceDeregister no more 


than once for a service or application, regardless of how many calls were made on the 
__ Service or application’s behalf. | . 


Parameters 
dwTracelD 
The handle returned by the calling service or application’s initial TraceRegister call. 


Return Values 
If the function succeeds, the return value is 0. 


If the function fails, the return value is an error code. Call GetLastError for further 
information. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Rtutils.h. 

Library: Use Rtutils.lib. 


About Tracing, Tracing Reference, TraceRegister, TracePrintf, TraceVprintt, 
TracePuts, TraceDump 7 


TraceDump 


The TraceDump function outputs a hexadecimal dump of size dwByteCount, prefixed 
with the name associated with the calling service or application’s dwTracelD, the 


associated Thread identifier used with the RRAS tracing functionality, the current system 
time, and a brief description of the dump. 
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Parameters 


dwTracelD 
The handle returned by the calling service or application’s initial TraceRegister call. 


IpbBytes 
A pointer to the buffer from which the hex dump is to be generated 


dwByteCount 
_ The number of bytes to dump from the buffer. 


dwGroupSize 
The output’s byte grouping size. Valid values are 1, 2, or 4. 


bAddressPrefix | 
Boolean value that determines whether each line of the hex dump has its memory 
address as a prefix. A value of TRUE ie nee the memory address. _ 


loszPrefix 
Pointer to the prefix. 


Return Values 
Successful execution of TraceDump returns the number of characters output. 


Otherwise, TraceDump returns zero. Call GetLastError to get the error code. 


Remarks 


TraceDump generates debug style dumps, with the byte- ordering dependent on the 
processor’s endian setting. Also note that the last line of the dump is padded with 


Zeroes. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Rtutils.h. 

Library: Use Rtutils.lib. 


About Tracing, Tracing Reference, TraceDumpEx, TraceRegister, TraceDeregister, 
TracePrintf, TraceVprintf, TracePuts- 
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TraceDumpEx 


The TraceDumpEx function outputs a hexadecimal dump of size dwByteCount. 
TraceDumpEx differentiates itself from TraceDump in its Extended (Ex) output options, 
implemented through the use of non-zero dwFlags values. Output from TraceDumpEx 
can include information with a prefix of the name associated with the calling service or 
application’s dwTracelD, the associated Thread identifier used with the RRAS tracing 
functionality, the current system time, and a brief description of the dump. 


Parameters 


dwTracelD 
The handle returned by the calling service or application’s initial TraceRegister call. 


dwFlags 7 
Flags that control appearance of TraceDumpEx output. Ensure dwFlags is one or 
more of the following: 


TRACE_NO_STDINFO | 
Suppresses output of the standard information associated with dwTracelD. 


TRACE_USE_ MASK 
Determines whether file and/or console output will be generated by comparing the 
high-order word of dwFlags against registry values FileTracingMask and 
ConsoleTracingMask. | | 
lpbBytes 
A pointer to the buffer from which the hex dump is to be generated. 
dwByteCount | 
The number of bytes to dump from the buffer. 


OdwGroupSize 
The output’s byte grouping size. Valid values are 1, 2, or 4. 


bAddressPrefix 
Boolean value that determines whether each line of the hex dump is prefixed with its 
memory address. A value of TRUE includes the memory address. 

loszPrefix | 
Pointer to the prefix. 
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Return Values 
Successful execution of TraceDump returns the number of characters output. 


Otherwise, TraceDump returns zero. Call GetLastError to get the error code. 


Remarks 


TraceDumpEx generates debug style dumps, with the byte-ordering dependent on the 
processor s endian setting. Also note that the last line of the amp! is padded with 


zeroes. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. — 

Header: Declared in Rtutils.h. 

Library: Use Rtutils.lib. 


About Tracing, Tracing Reference, TraceDump, TraceRegisterEx, TracePrintfEx, 
TraceVprintfEx, TracePutsEx 


TracePrintf 
The TracePrintf function outputs tracing information, including the following: calling 
service or application’s name, the current time, and tracing information in the format 


specified by the optional argument or arguments included in /oszFormat. See the note 
below for an example of TracePrintf results. 


Parameters 
dwTracelD 
The handle returned by the calling service or application’ S initial TraceRegister call. 


IpszFormat 
Pointer to a null- terminated string containing printt-stye format contfol information. 


~ One or more optional egamnen depending on the format control specified in 
lpszFormat. 
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Return Values 
lf the function succeeds, TracePrintf returns the number of characters ouput excluding 
the terminating null- character. 


lf the function fails, the return value will be zero. This may also indicate that tracing is 
disabled in the registry. See Tracing Configuration for more information. 


Remarks | 

The following is an example for the output from TracePrintf. In the following example, 
the service or application calling TracePrintf is IPRIP, and its associated Thread 
identifier for use with the RRAS tracing functionality is 129: 


To suppress the prefixes, use TracePrintfEx. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Rtutils.h. 

Library: Use Rtutils. lib. 


About Tracing, Tracing Reference, TracePrintfEx, TraceRegister, TraceDeregister, 
TraceVprintf, TracePuts, TraceDump 


‘TracePrintfEx 


The TracePrintfEx function outputs tracing information. TracePrintfEx differentiates 
itself from TracePrintf by offering Extended options (Ex) implemented through non-zero 
dwFlags values. Output generated by TracePrintfEx includes up to the following: calling 
service or application name, the current time, and tracing information in the format 
specified by the optional included in /oszFormat. 


lf dwFlags is zero, TracePrintfEx behaves exactly as TracePrintt. 
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Parameters 


dwTrace/lD 
The handle returned by the calling service or application s initial TraceRegister call. 


dwFlags 
Specifies optional flags that control appearance of TracePrintfEx output. Ensure 
dwFlags is one or more of the following: 


TRACE_NO_STDINFO 
Suppresses output of the standard information associated with GWA taco! 


TRACE_USE_MASK | 
Determines whether file and/or console output will be generated by comparing the 
high-order word of dwFlags against registry values FileTracingMask and 
ConsoleTracingMask. 

lpszFormat 
Pointer to a null- terminated string containing printf-style format control information. 


“One or more optional arguments, depending on the format control specified in 
loszFormat. 


Return Values | | 
If the function is successful, TracePrintfEx returns the number of characters output, 
excluding the terminating null-character. 


If the function fails, the return value is zero. This may indicate that tracing is disabled in 
the registry. See Tracing Configuration for more information. 


Windows NT/2000: Requires Windows 2000. Available asa redistributable for 
Windows NT 4.0. 

Header: Declared in Rtutils.h. 

Library: Use Rtutils.lib. 


About Tracing, Tracing Reference, TracePrintf, TraceRegisterEx, TraceVprintfEx, 
TracePutsEx, TraceDumpEx 
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-TracePuts 


The TracePuts function is an efficient way to retrieve information associated with a 
registered service or application’s identifier (dwTrace/D). TracePuts also outputs the 
string literal passed as the function’s second argument. 


Parameters 
dwTrace!D | 

The handle returned by the calling service or application’s initial TraceRegister call. 
IpszString 

The string to be output. 


Return Value 


lf the function is successful, TracePuts returns the number of characters output, 
excluding the terminating null-character. | 


If the function fails, the return value is zero. This may also indicate that tracing is 
disabled in the registry. See Tracing Configuration for more information. 


Remarks 


TracePuts outputs the name associated with dwTracelD, the internal thread identifier 
used to identify the caller, the current time, and the literal string specified by JoszString. 
Since TracePuts performs no formatting on its arguments, it is more efficient than 
TracePrintf or TraceVprintf. To suppress the prefixes and prevent output from starting 
on a new line, see TracePutsEx. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. | | oo 


Header: Declared in Rtutils.h. 
Library: Use Rtultils.lib. 


About Tracing, Tracing Reference, TracePutsEx, TraceRegister, TraceDeregister, 
TracePrintf, TraceVprintf, TraceDump 
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TracePutsEx 


The TracePutsEx function is an efficient way to retrieve information associated with a 
registered service or application’s identifier (dwTracelD). TracePutsEx differs from 
TracePuts in its Extended (Ex) flexibility with regard to output, achieved through the use 
of non-zero flags implemented with dwFlags. TracePutsEx also outputs the string literal 
passed as the function’s second argument. 


Parameters © 
dwTracelD 
The handle returned by the calling service or application’s initial TraceRegister call. 


dwFlags | 
Flags that control appearance of TracePutsEx output. Ensure dwFiags is one or 
more of the following: 


TRACE_NO_STDINFO | 
Suppresses output of the standard information associated with dwTracelD. 


TRACE_USE MASK 
Determines whether file and/or console output will be generated by comparing the 
high-order word of dwFlags against registry values FileTracingMask and 
ConsoleTracingMask. 
IpszSiring 
The string to be output. 


Return Values 


If the function is successful, TracePuts returns the number of characters output, 
excluding the terminating null-character. 


If the function fails, the return value is zero. This may indicate that tracing is disabled in 
the registry. See Tracing Configuration for more information. 


Windows NT/2000: Requires Windows 2000. Available 2 asa 4 redistributable for 
Windows NT 4.0. 

Header: Declared in Rtutils.h. 

Library: Use Rtutils. lib. 
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About Tracing, Tracing Reference, TracePuts, TraceRegisterEx, TracePrintfEx, 
_ TraceVprintfEx, TraceDumpEx 


TraceRegister 


Use the TraceRegister function to register services or applications with the tracing DLL. 
Its successful return value is an identifier that provides a handle to subsequent tracing 
functions available in Windows NT/Windows 2000. This function, or its extended 
functionality counterpart TraceRegisterEx, must be called before any other tracing 

functions are called. TraceDeregister or TraceDeregisterEx should be called when 
trace functions are no longer needed, in order to free resources. 


Parameters 


IpszCallerName 
Pointer to a null-terminated string containing the service or application name being 
registered. This is the name with which the service tracing functions will identify the 
caller. 


Return Values 


If successful, this function will return a DWORD to be used as the service or application’ S 
identifier (handle) for subsequent calls to tracing functions. 


If the function fails, INVALID_TRACEID is returned. This indicates the caller could not be 
registered. Call GetLastError to retrieve the error code. 


Remarks 


Upon successful execution of TraceRegister, configuration for the service or application 
calling TraceRegister will be created and kept in the registry path 
\System\CurrentControlSet\Services\Tracing\</pszCallerName> under the 
HKEY_LOCAL_MACHINE key. Such configuration parameters are kept intact, even if 
the service or application is deregistered from tracing utilities by calling TraceDeregister. 
If the registry entries cannot be created, the call to TraceRegister will fail. There are 
certain values within this key that can be modified to change the behavior of trace 
output. : 


EnableConsoleTracing 
A REG_DWORD that determines whether tracing to the console is enabled. Console 
tracing is enabled if the value is non-zero. The default value is 1. 
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EnableFileTracing 
A REG_DWORD that determines whether tracing information should be sent to a file 
called /pzsCallerName.log. File tracing is enabled if the value is non-zero. The default 
value is 1. 


ConsoleTracingMask — 
A REG_DWORD that regulates whether output from an extended tracing function Call 
is directed to the console. The bits in the high-order word correspond to components 
in the client; if a call to an extended output function has the flag TRACE_USE_MASK 
set, the value of ConsoleTracingMask is compared to the flag sent to the function to 
determine whether to send output to the console. The default value is OxFFFFOOOO. 


FileT racingMask 
A REG_DWORPD that works in a similar way to Console TracingMask, regulating 
whether the extended tracing function calls direct their output to File tracing The 
default value is OxFFFFOOOO. 


MaxFileSize 
A REG_DWORD that defines the maximum size a tracing file can become before it is 
renamed. The default value is 0x10000. 


FileDirectory 
A REG_EXPAND_SZ that controls the directory i in which the tracing file is created. 
The default is %windir%\tracing. 


Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Rtutils.h. 

Library: Use Rtutils.lib. 


About Tracing, Tracing Reference, TraceRegisterEx, TraceDeregister, TracePrintt, 
TraceVprintf, TracePuts, TraceDump 


TraceRegisterEx 


The TraceRegisterEx function registers services or applications with the tracing DLL. 
TraceRegisterEx differentiates itself from TraceRegister by providing Extended 
flexibility (Ex) with regard to the creation or reading of registry keys. 
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Successful execution of TraceRegisterEx returns an identifier used as a handle to 
subsequent tracing functions available in Microsoft® Windows NT®/Windows® 2000. 
This function, or its counterpart TraceRegister, must be called before any other tracing 

functions are called. If no flags are passed to TraceRegisterEx (if dwFlags is zero), 
TraceRegisterEx behaves exactly as TraceRegister. TraceDeregister or 
TraceDeregisterEx should be called when trace functions are no longer needed, in 
order to free resources. 


Parameters 

lpszCallerName 
A pointer to a null-terminated string containing the service or application name being 
registered. This is the name with which the service tracing functions will identify the 
caller. 


dwFlags 
Flags that control the nature of the calling service or application’s registration. Ensure 
dwFlags is one or more of the following: 


TRACE USE CONSOLE | 
Tracing output is sent to the console; using this parameter avoids loading or writing 
settings from the registry. 


TRACE_USE_FILE 
Tracing output is sent to a file; using this parameter avoids reading or writing 
settings from the registry. 


Return Values 


Success will return a DWORD to be used as the service or eppncetien identifier (handle) 
for subsequent calls to tracing functions. 


INVALID_TRACEID 
The caller could not be registered. Call GetLastError to retrieve the error code. 


Remarks 


Upon successful execution of TraceRegisterEx, configuration for the service or 
application calling TraceRegisterEx will be taken from the parameters passed as 
dwFlags, and registry reads or writes will not occur. If the value of dwFlags is zero, then 
a call to TraceRegisterEx will behave exactly as a call to TraceRegister, and 
initialization and configuration parameters will be created and kept in the registry path 
\System\CurrentControlSet\Services\Tracing\</pszCallerName> under the 
HKEY_LOCAL_MACHINE key. 
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Windows NT/2000: Requires Windows 2000. Available as a redistributable for 
Windows NT 4.0. 

Header: Declared in Rtutils.h. 
Library: Use Rtutils.lib. 


About Tracing, Tracing Reference, TraceRegister, TracePrintfEx, TraceVprintfEx, 
TracePutsEx, TraceDumpEx | 


TraceVprintf 


Functionality of TraceVprinttf is very similar to that of TracePrintf, except that it takes 
a prepared variable argument list as its third variable. See TracePrintf for more 
information. 


Parameters 


dwTracelD 
The handle returned by the calling service or application’s initial TraceRegister call. 


lpszFormat 
Pointer to a null-terminated string containing printf-style format control information. 


arglist 
A prepared list of printf()-style arguments that define the format of TraceVprintf 
Output. 


Return Values sy ; | | 


If the function succeeds, TraceVprintf returns the number of characters output, 
excluding the terminating null-character. 


lf the function fails, the return value is zero. This may also indicate that tracing is 
disabled in the registry. See Tracing Configuration for more information. 
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Return Values 


If the function is succesful, TraceVprintfEx returns the number of characters output, 
excluding the terminating null-character. 


If the function fails, the return value is zero. This may indicate that tracing is disabled in 
the registry. See Tracing Configuration for more information. 


Windows NT/2000: Requires Windows 2000. Available asa redistributable for 
Windows NT 4.0. 

Header: Declared in Rtutils.h. 

Library: Use Rtutils.lib. 


About t Tracing, T Tracing Reference, TraceVprintt, TraceRegisterEx, TracePrintfEx, 
TracePutsEx, TraceDumpEx 
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INDEX 


Networking Services Programming Elements — 
Alphabetical Listing 


This final part, found in each volume in the Networking Services Library, provides a 
comprehensive programming element index that has been designed to make your life 
easier. 


Rather than cluttering the TOCs of each individual volume in this library with the names 
of programming elements, I've relegated such per-element information to a central 
location: the back of each volume. This index points you to the volume that has the 
information you need, and organizes the information in a way that lends itself to easy 
use. 


Also, to keep you as informed and up-to-date as possible about Microsoft technologies, 

I've created (and maintain) a live Web-based document that maps Microsoft 

technologies to the locations where you can get more information about them. The 
following link gets you to the live index of technologies: 


www.iseminger.com/winprs/technologies 


The format of this index is in a constant state of improvement. I've designed it to be as 
useful as possible, but the real test comes when you put it to use. If you can think of 
ways to make improvements, send me feedback at winprs @ microsoft.com. While | can't 
guarantee a reply, I'll read the input, and if others can benefit, | will incorporate the idea 
into future libraries. 


Locators are arranged by Volume Number followed by Page Number. 


A B 
ACCOD berweil aiccctceacticcnceputecie es aitinternns Vol. 1, 133 EDUC sdcetinte Piwneca utah vaedes occas enieewiatany eal Vol. 1, 139 
PCCODIEX noe esta ccetecteneesda a eye cas Vol. 1, 135 Binding Option Constants............ Vol. 3, 333 
ACTION_HEADER.............ccccceeeseeeees Vol. 2, 147 Binding Time-out Constants ............. Vol. 3, 333 
ADAPTER_STATUS. ............ccceeeeeees Vol. 2, 148 BLOB eal nse tien ars aatiesaeress Vol. 1, 378 
Addinterface .............:ccc0 Gaiety Vol. 5, 266 BlockConvertServicesToStatic ......... Vol. 5, 316 
ACdIPACIeSS ...........cccsecceseeceeeeeeenaes Vol. 2, 239 BlockDeleteStaticServices......... aga Vol. 5, 317 
ADDRESS_LIST_DESCRIPTOR..... Vol. 1, 835 
AFPROTOCOLS .........005 Sie So tbazad Vol. 1, 377 
PSMA secretes anccieetectetee ete Vol. 2, 336 C | 
AsnCounter64 coseeneenesneeeseeneeanesaeenerans Vol. 2, 338 CbpACMItRSVPMSG.....e.ccsccecsesseeseesees Vol. 1, 860 
AsnObjectidentifier ..........csssceeee Vol. 2, 339 cbpGetRsvpObjects........sssessss Vol. 1, 861 
AsnOctetString stonaea Caleta coisa mares Vol. 2, 339 Change Notification Flags... Vol. 5, 505 
_ Authentication-Level Constants ....... Vol. 3,330 Ci AddFlowComplete ......sssesssssssssseeee Vol. 1, 830 
_ Authentication-Service Constants... Vol. 3, 331 CiDeleteFlowComplete .........c:cec Vol. 1, 831 


Authorization-Service Constants...... Vol. 3, 332 CIModifyFlowComplete .........ss:ss::+0+-- Vol. 1, 831 
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